{ "openapi": "3.1.0", "info": { "title": "Vitrina API", "version": "17.37.0", "description": "Public API for managing AI agents, tools, conversations, tickets, and integrations. All endpoints live under `/api/v1` and require a `Bearer ` (either an `sk_*` API key or a Supabase JWT). State-changing endpoints accept the optional `Idempotency-Key` header." }, "servers": [ { "url": "/api/v1" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Either an `sk_*` API key or a Supabase JWT." }, "PublishableKeyAuth": { "type": "http", "scheme": "bearer", "description": "A browser-safe `pk_*` publishable widget key (ADR 0033), origin-locked, fixed scopes stock:read+leads:intake+widget:chat+appointments:intake." }, "DeviceAgentBearerAuth": { "type": "http", "scheme": "bearer", "description": "A `va_*` per-agent token minted by `POST /device-agent/claim` — identifies exactly one device_agent row, never a tenant credential." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "field_errors": { "type": "object", "additionalProperties": { "type": "string" } }, "requestId": { "type": "string" } }, "required": [ "code", "message" ] } }, "required": [ "error" ] }, "Author": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "member", "api_key", "ai_agent", "system", "contact" ], "description": "`member` = a workspace member (in the app, or through a personal token / connected app — see `via`); `api_key` = an API key, a workspace integration credential («CRM propio (API)»); `ai_agent` = the AI agent; `system` = the platform itself; `contact` = the customer." }, "id": { "type": [ "string", "null" ], "description": "The member's user id, the API key id, the AI agent id or the contact id. Null for `system` and for a contact not yet identified. Branch on `kind` + `id`, never on `name`." }, "name": { "type": [ "string", "null" ], "description": "Display name. For an API key it is the key's name AS IT WAS when it acted (renaming or revoking the key does not rewrite history); for a member, their current profile name. Null when unknown." }, "via": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connected_app", "personal_token" ], "description": "The credential a member acted through." }, "name": { "type": "string", "description": "The connected app's name («Claude») or the personal token's name. May be empty when unresolvable." } }, "required": [ "kind", "name" ], "description": "Present when a MEMBER acted through a connected app or a personal token: the member is still the author, with the app recorded beside them («Camila vía Claude»)." } }, "required": [ "kind", "id", "name" ] }, "NotificationTarget": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "record" ] }, "record": { "type": "string", "enum": [ "conversation", "contact", "lead", "busqueda", "appointment", "ai_agent", "price_approval", "cotizacion", "bank_movement", "vehicle", "whatsapp_flow", "campaign", "negocio" ] }, "id": { "type": "string", "format": "uuid" }, "tab": { "type": "string" }, "sub": { "type": "string", "format": "uuid" } }, "required": [ "kind", "record", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "screen": { "type": "string", "enum": [ "conversations", "busquedas", "contacts_demand", "clinic_call_today", "clinic_inventory", "transferencias", "pipelines", "price_approvals", "campaigns" ] }, "filter": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "kind", "screen", "filter" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "page" ] }, "page": { "type": "string", "enum": [ "settings.channels", "settings.channel", "settings.webhooks", "finanzas.bancos", "finanzas.flujo_de_caja", "finanzas.f29", "finanzas.contraparte", "settings.api_keys", "settings.billing", "settings.seguimientos", "settings.templates", "settings.marketplaces", "settings.notifications", "settings.payment_methods", "ai_agents", "ads", "onboarding", "vehicles.marketplaces", "calendar" ] }, "params": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "kind", "page" ] } ], "description": "Where the notification leads — a typed destination, never a URL. `record` = one subject (a conversation, a lead, an appointment…), `list` = a filtered list (e.g. the Búsquedas a daily summary counted), `page` = a fixed screen (e.g. one channel’s settings). The UI routes each kind with one table." }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "description": "Registry key, e.g. `assigned`, `busqueda.daily_summary`." }, "category": { "type": "string" }, "actor_id": { "type": [ "string", "null" ], "format": "uuid" }, "entity_type": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "object", "additionalProperties": {}, "description": "Render snapshot; the UI renders copy from `type` + `data`." }, "target": { "allOf": [ { "$ref": "#/components/schemas/NotificationTarget" }, { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "record" ] }, "record": { "type": "string", "enum": [ "conversation", "contact", "lead", "busqueda", "appointment", "ai_agent", "price_approval", "cotizacion", "bank_movement", "vehicle", "whatsapp_flow", "campaign", "negocio" ] }, "id": { "type": "string", "format": "uuid" }, "tab": { "type": "string" }, "sub": { "type": "string", "format": "uuid" } }, "required": [ "kind", "record", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "screen": { "type": "string", "enum": [ "conversations", "busquedas", "contacts_demand", "clinic_call_today", "clinic_inventory", "transferencias", "pipelines", "price_approvals", "campaigns" ] }, "filter": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "kind", "screen", "filter" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "page" ] }, "page": { "type": "string", "enum": [ "settings.channels", "settings.channel", "settings.webhooks", "finanzas.bancos", "finanzas.flujo_de_caja", "finanzas.f29", "finanzas.contraparte", "settings.api_keys", "settings.billing", "settings.seguimientos", "settings.templates", "settings.marketplaces", "settings.notifications", "settings.payment_methods", "ai_agents", "ads", "onboarding", "vehicles.marketplaces", "calendar" ] }, "params": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "kind", "page" ] }, { "type": "null" } ] } ] }, "secondary_target": { "allOf": [ { "$ref": "#/components/schemas/NotificationTarget" }, { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "record" ] }, "record": { "type": "string", "enum": [ "conversation", "contact", "lead", "busqueda", "appointment", "ai_agent", "price_approval", "cotizacion", "bank_movement", "vehicle", "whatsapp_flow", "campaign", "negocio" ] }, "id": { "type": "string", "format": "uuid" }, "tab": { "type": "string" }, "sub": { "type": "string", "format": "uuid" } }, "required": [ "kind", "record", "id" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "list" ] }, "screen": { "type": "string", "enum": [ "conversations", "busquedas", "contacts_demand", "clinic_call_today", "clinic_inventory", "transferencias", "pipelines", "price_approvals", "campaigns" ] }, "filter": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "kind", "screen", "filter" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "page" ] }, "page": { "type": "string", "enum": [ "settings.channels", "settings.channel", "settings.webhooks", "finanzas.bancos", "finanzas.flujo_de_caja", "finanzas.f29", "finanzas.contraparte", "settings.api_keys", "settings.billing", "settings.seguimientos", "settings.templates", "settings.marketplaces", "settings.notifications", "settings.payment_methods", "ai_agents", "ads", "onboarding", "vehicles.marketplaces", "calendar" ] }, "params": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "kind", "page" ] }, { "type": "null" } ] } ] }, "live": { "type": "boolean", "description": "A standing condition: refreshed in place, marked read when it ends." }, "read_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "type", "category", "actor_id", "entity_type", "entity_id", "data", "target", "secondary_target", "live", "read_at", "created_at" ] }, "NotificationPreferenceCatalog": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "important", "all", "custom" ] }, "push_enabled": { "type": "boolean" }, "categories": { "type": "array", "items": { "type": "string", "enum": [ "inbox", "agenda", "sales", "followups", "approvals", "payments", "agents", "integrations", "finanzas", "safety", "account" ] } }, "types": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "category": { "type": "string", "enum": [ "inbox", "agenda", "sales", "followups", "approvals", "payments", "agents", "integrations", "finanzas", "safety", "account" ] }, "slug": { "type": "string", "description": "i18n slug: the UI renders `notif..title` / `.when`." }, "mandatory": { "type": "boolean" }, "locked_reason": { "type": [ "string", "null" ] }, "bell_mutable": { "type": "boolean" }, "delivery": { "type": "string", "enum": [ "immediate", "live", "digest" ] }, "channels": { "type": "object", "properties": { "in_app": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unavailable", "locked", "always", "on", "off" ], "description": "`unavailable` = not sent this way (or WhatsApp not armed by the workspace); `locked` = mandatory; `always` = the bell of a type you must act on; `on` / `off` = your choice, or the default when you never chose." }, "default": { "type": [ "string", "null" ], "enum": [ "on", "off", "locked", "workspace" ] } }, "required": [ "state", "default" ] }, "email": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unavailable", "locked", "always", "on", "off" ], "description": "`unavailable` = not sent this way (or WhatsApp not armed by the workspace); `locked` = mandatory; `always` = the bell of a type you must act on; `on` / `off` = your choice, or the default when you never chose." }, "default": { "type": [ "string", "null" ], "enum": [ "on", "off", "locked", "workspace" ] } }, "required": [ "state", "default" ] }, "push": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unavailable", "locked", "always", "on", "off" ], "description": "`unavailable` = not sent this way (or WhatsApp not armed by the workspace); `locked` = mandatory; `always` = the bell of a type you must act on; `on` / `off` = your choice, or the default when you never chose." }, "default": { "type": [ "string", "null" ], "enum": [ "on", "off", "locked", "workspace" ] } }, "required": [ "state", "default" ] }, "whatsapp": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unavailable", "locked", "always", "on", "off" ], "description": "`unavailable` = not sent this way (or WhatsApp not armed by the workspace); `locked` = mandatory; `always` = the bell of a type you must act on; `on` / `off` = your choice, or the default when you never chose." }, "default": { "type": [ "string", "null" ], "enum": [ "on", "off", "locked", "workspace" ] } }, "required": [ "state", "default" ] } }, "required": [ "in_app", "email", "push", "whatsapp" ] } }, "required": [ "key", "category", "slug", "mandatory", "locked_reason", "bell_mutable", "delivery", "channels" ] } } }, "required": [ "preset", "push_enabled", "categories", "types" ] }, "NotificationPreferencesUpdate": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "important", "all", "custom" ], "description": "`important` = back to the defaults (clears your per-type choices); `all` = every switchable cell on; `custom` = keep your cells." }, "changes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 80 }, "channel": { "type": "string", "enum": [ "in_app", "email", "push", "whatsapp" ] }, "enabled": { "type": "boolean" } }, "required": [ "key", "channel", "enabled" ] }, "maxItems": 200 }, "push_enabled": { "type": "boolean" } } }, "TenantSettingsPublic": { "type": "object", "properties": { "trade_in": { "type": "object", "properties": { "price_table": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 80 }, "top": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "min_battery_pct": { "type": "integer", "minimum": 1, "maximum": 100 }, "low_battery_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "direct_purchase": { "type": "boolean" } }, "required": [ "model", "top", "used" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "not_bought": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 200 }, "floor_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "perfect_floor_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "rounding": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "perfect_battery_pct": { "type": "integer", "minimum": 1, "maximum": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "price_table" ], "additionalProperties": false, "description": "Trade-in buy table («parte de pago»), for a business that buys used devices: `price_table` rows `{model, top, used, min_battery_pct?, low_battery_factor?, direct_purchase?}` (`top` = max paid for a flawless unit, `used` = with normal wear, whole currency units; capacity does not change the value; `min_battery_pct` = a known battery under it is not bought; `low_battery_factor` (0–1) = a known battery under `perfect_battery_pct` caps the price at `used × low_battery_factor` instead of `used`; `direct_purchase: false` = the model is taken only as part of the payment for another item, never bought outright — absent = true), `not_bought` (models never bought), `floor_factor` (0–1, default 0.7: the low end for a unit with issues or unknown condition is `used × floor_factor`), `perfect_floor_factor` (0–1, default 0.85: the low end for a flawless unit is `used × perfect_floor_factor`, its high end is `top`), `rounding` (default 10000), `perfect_battery_pct` (default 90), `currency` (default CLP). On an ecommerce workspace its presence offers the agents the `estimate_trade_in` tool (a wide range of what the customer would still pay) and the `quote_buyback` tool (the most paid for one device sold outright, or the discount for a `direct_purchase: false` model); the business’s own site reads it at `GET /storefront/trade-in`. Replaced whole on write; `null` clears it." }, "notifications": { "type": "object", "properties": { "staff_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" } } }, "unanswered_supervisor_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" }, "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "delay_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "description": "Minutes of open time a conversation waits on the team before the supervisors get the WhatsApp, once per episode. Unset = 60." } } }, "reminder_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" } }, "description": "Staff WhatsApp on every «sin respuesta» reminder, to the assignee (template aviso_sigue_esperando_v1). Opt-in: each send costs a WhatsApp conversation." }, "booking_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" }, "change_template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" } } }, "visit_watchers_whatsapp": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "user_ids" ] }, "finanzas_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" }, "digest_template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$", "description": "The weekly Finanzas digest template (resumen_finanzas_semanal_v1), wired on approval." } } }, "stock_alert": { "type": "object", "properties": { "stage_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "description": "Lead stages that trigger the «Stock faltante» check when a lead moves into them. Empty turns it off." } }, "required": [ "stage_ids" ] } }, "description": "Workspace notification rails. The staff WhatsApp rails (`staff_whatsapp`, `unanswered_supervisor_whatsapp`, `booking_whatsapp`, `reminder_whatsapp`, `finanzas_whatsapp`) are opt-in: arming one (`enabled: true` with an `account_id`) submits its template to Meta on that number and wires it on approval. Each rail sent replaces that rail whole; rails not sent are kept." }, "staff_rails": { "type": "object", "properties": { "staff_whatsapp": { "type": "object", "properties": { "armed": { "type": "boolean", "description": "The rail is switched on (`enabled: true`)." }, "template_state": { "type": "string", "enum": [ "off", "no_number", "missing", "pending", "approved", "rejected", "blocked" ], "description": "Worst state across the rail templates (blocked, rejected, missing, pending, approved); `off` when not armed or nothing to provision; `no_number` when armed without a sending number." }, "reason": { "type": [ "string", "null" ] }, "wired": { "type": "boolean", "description": "The rail has its template name set (by an admin or on approval)." }, "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "state": { "type": "string", "enum": [ "missing", "pending", "approved", "rejected", "blocked" ] }, "rejection_reason": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "language", "state", "rejection_reason" ] } } }, "required": [ "armed", "template_state", "reason", "wired", "templates" ] }, "unanswered_supervisor_whatsapp": { "type": "object", "properties": { "armed": { "type": "boolean", "description": "The rail is switched on (`enabled: true`)." }, "template_state": { "type": "string", "enum": [ "off", "no_number", "missing", "pending", "approved", "rejected", "blocked" ], "description": "Worst state across the rail templates (blocked, rejected, missing, pending, approved); `off` when not armed or nothing to provision; `no_number` when armed without a sending number." }, "reason": { "type": [ "string", "null" ] }, "wired": { "type": "boolean", "description": "The rail has its template name set (by an admin or on approval)." }, "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "state": { "type": "string", "enum": [ "missing", "pending", "approved", "rejected", "blocked" ] }, "rejection_reason": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "language", "state", "rejection_reason" ] } } }, "required": [ "armed", "template_state", "reason", "wired", "templates" ] }, "booking_whatsapp": { "type": "object", "properties": { "armed": { "type": "boolean", "description": "The rail is switched on (`enabled: true`)." }, "template_state": { "type": "string", "enum": [ "off", "no_number", "missing", "pending", "approved", "rejected", "blocked" ], "description": "Worst state across the rail templates (blocked, rejected, missing, pending, approved); `off` when not armed or nothing to provision; `no_number` when armed without a sending number." }, "reason": { "type": [ "string", "null" ] }, "wired": { "type": "boolean", "description": "The rail has its template name set (by an admin or on approval)." }, "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "state": { "type": "string", "enum": [ "missing", "pending", "approved", "rejected", "blocked" ] }, "rejection_reason": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "language", "state", "rejection_reason" ] } } }, "required": [ "armed", "template_state", "reason", "wired", "templates" ] }, "finanzas_whatsapp": { "type": "object", "properties": { "armed": { "type": "boolean", "description": "The rail is switched on (`enabled: true`)." }, "template_state": { "type": "string", "enum": [ "off", "no_number", "missing", "pending", "approved", "rejected", "blocked" ], "description": "Worst state across the rail templates (blocked, rejected, missing, pending, approved); `off` when not armed or nothing to provision; `no_number` when armed without a sending number." }, "reason": { "type": [ "string", "null" ] }, "wired": { "type": "boolean", "description": "The rail has its template name set (by an admin or on approval)." }, "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "state": { "type": "string", "enum": [ "missing", "pending", "approved", "rejected", "blocked" ] }, "rejection_reason": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "language", "state", "rejection_reason" ] } } }, "required": [ "armed", "template_state", "reason", "wired", "templates" ] }, "reminder_whatsapp": { "type": "object", "properties": { "armed": { "type": "boolean", "description": "The rail is switched on (`enabled: true`)." }, "template_state": { "type": "string", "enum": [ "off", "no_number", "missing", "pending", "approved", "rejected", "blocked" ], "description": "Worst state across the rail templates (blocked, rejected, missing, pending, approved); `off` when not armed or nothing to provision; `no_number` when armed without a sending number." }, "reason": { "type": [ "string", "null" ] }, "wired": { "type": "boolean", "description": "The rail has its template name set (by an admin or on approval)." }, "templates": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "language": { "type": "string" }, "state": { "type": "string", "enum": [ "missing", "pending", "approved", "rejected", "blocked" ] }, "rejection_reason": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "language", "state", "rejection_reason" ] } } }, "required": [ "armed", "template_state", "reason", "wired", "templates" ] } }, "required": [ "staff_whatsapp", "unanswered_supervisor_whatsapp", "booking_whatsapp", "finanzas_whatsapp", "reminder_whatsapp" ], "description": "Read-only: the template state of each staff WhatsApp rail. Ignored on write." }, "name": { "type": "string", "description": "Workspace display name." }, "timezone": { "type": "string", "description": "IANA time zone, e.g. `America/Santiago`." }, "language": { "type": "string", "description": "Default language, e.g. `es`." }, "currency": { "type": "string", "description": "ISO 4217 currency, e.g. `CLP`." }, "date_format": { "type": "string", "enum": [ "latam", "us", "iso" ] }, "website": { "type": "string", "description": "The workspace's declared public website." }, "product_url_template": { "type": [ "string", "null" ], "description": "Where the store's own product pages live, e.g. `https://macphones.cl/iphone/{slug}`. Placeholders (the product's fields): `{slug}` (title as a URL slug), `{sku}`, `{id}`, `{brand}`. The agent's stock search returns each product's page link when this is set; a product can override it with `attributes.public_url`. Send `null` or an empty string to clear." }, "ads": { "type": "object", "properties": { "tag_choice": { "type": [ "string", "null" ], "enum": [ "site", "no_site" ], "description": "How the «Instalar el tag» step was answered: `site` (the tag goes on the workspace website) or `no_site` (no website; skipped on purpose). Absent/`null` = never answered." }, "tag_choice_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Server-stamped on every `tag_choice` write." }, "goal": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "outcomes", "value", "roas" ], "description": "`outcomes` = results from ads this month; `value` = attributed value (CLP); `roas` = return (×)." }, "target": { "type": "number", "exclusiveMinimum": 0, "description": "The month’s target. `roas` ≤ 100; `value` ≤ 10^10; `outcomes` ≤ 10^6." }, "period": { "type": "string", "enum": [ "month" ], "description": "The only period: the calendar month." } }, "required": [ "kind", "target", "period" ], "additionalProperties": false, "description": "The monthly goal the Ads hero measures pace against." }, "specialty_map": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "match": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A fragment of the campaign, ad-set or ad name (accent- and case-insensitive)." }, "especialidad": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The roster specialty it books (e.g. «TTM»)." }, "professional_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "The vendor professional ids (`clinic_professional.external_id`) it books with." }, "visit_minutes": { "type": "integer", "minimum": 5, "maximum": 480, "description": "How long the entry visit (the evaluation) takes." }, "evaluation_price": { "type": "integer", "minimum": 0, "maximum": 100000000, "description": "What the entry visit costs (CLP)." } }, "required": [ "match" ], "additionalProperties": false }, "description": "Which specialty each campaign / ad set / ad books (a name fragment → especialidad, professionals, entry-visit minutes and price). The agenda-capacity check behind «Pausar» / «Subir» reads it first; absent = the name match." }, "goal_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Server-stamped on every `goal` write." }, "goal_by": { "type": [ "string", "null" ], "description": "Who last wrote the goal: the member's user id, or the API key id." }, "dismissed_actions": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" }, "description": "`{ [action key]: until ISO }` — Ads actions hidden until that instant; expired entries are pruned on every write." } }, "description": "Vitrina Ads workspace choices; absent until first answered." }, "voice": { "type": "object", "properties": { "brand_name": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[^{}\\r\\n\\t]+$", "description": "Brand name templates say literally (\"te escribimos de Automec\"). Absent = the workspace name." }, "register": { "type": "string", "enum": [ "tu", "usted" ], "description": "How templates address people. Absent = `usted` for healthcare, `tu` otherwise." }, "opening_marks": { "type": "string", "enum": [ "none", "keep" ], "description": "«Signos de apertura» in the AI's chat replies and follow-ups. `none` (default when absent): no opening «¿» «¡», the way people type in a Chilean chat; removed at send time from every AI message. `keep`: the agent writes them. An agent can override it (`behavior_policies.opening_marks`)." }, "agent_register": { "type": "string", "enum": [ "tu", "usted", "mirror" ], "description": "«Trato» of the AI agents: `tu`, `usted`, or `mirror` (tú until the customer uses usted). Absent: each agent's own instructions decide. Wins over the agent's instructions; an agent can override it (`behavior_policies.register`)." } }, "additionalProperties": false, "description": "The stored tenant voice (brand name + tú/usted) customer-facing WhatsApp templates are written in; absent until set." }, "agent_language": { "type": "object", "properties": { "banned_terms": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 60, "pattern": "^[^\\r\\n\\t]+$" }, "maxItems": 100, "description": "Words the AI agent must never write to customers (case- and accent-insensitive, whole words), merged with the platform es-CL list. A reply that uses one is rewritten without it before it is sent. Up to 100 terms of 2 to 60 characters." } }, "additionalProperties": false, "description": "The AI agent's vocabulary: the workspace's banned terms; absent until set." }, "voice_resolved": { "type": "object", "properties": { "brand_name": { "type": "string" }, "register": { "type": "string", "enum": [ "tu", "usted" ] }, "brand_name_source": { "type": "string", "enum": [ "stored", "workspace_name" ] }, "register_source": { "type": "string", "enum": [ "stored", "vertical_default" ] } }, "required": [ "brand_name", "register", "brand_name_source", "register_source" ], "description": "Read-only: the voice templates are actually written in (stored value or default), with where each part came from. Ignored on write." }, "slack_webhook_url": { "type": "string", "enum": [ "••••" ], "description": "Write-only secret: the Slack incoming-webhook URL is never returned. `••••` when one is configured; absent otherwise. Read `slack_webhook_configured` instead." }, "slack_webhook_configured": { "type": "boolean", "description": "Whether a Slack incoming webhook is configured for workspace alerts." }, "manage_workshop": { "type": "boolean", "description": "«Gestionar taller en Vitrina» (automotive). On: the workspace has the «Servicio de vehículos» workshop board next to Soporte. Never set → reads true exactly when that board already exists. Writing `true` creates the board (idempotent; refused with 400 outside the automotive vertical); `false` removes it only while no ticket was ever placed on it — a board in use is kept (see `workshop_board.in_use`)." }, "workshop_board": { "type": "object", "properties": { "pipeline_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The «Servicio de vehículos» board; null when there is none." }, "in_use": { "type": "boolean", "description": "A ticket was ever placed on the board; turning `manage_workshop` off keeps it." } }, "required": [ "pipeline_id", "in_use" ], "description": "Read-only: the workshop board `manage_workshop` governs. Ignored on write." } } }, "TenantSettingsPublicWrite": { "type": "object", "properties": { "trade_in": { "type": [ "object", "null" ], "properties": { "price_table": { "type": "array", "items": { "type": "object", "properties": { "model": { "type": "string", "minLength": 1, "maxLength": 80 }, "top": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "min_battery_pct": { "type": "integer", "minimum": 1, "maximum": 100 }, "low_battery_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "direct_purchase": { "type": "boolean" } }, "required": [ "model", "top", "used" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "not_bought": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 200 }, "floor_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "perfect_floor_factor": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 }, "rounding": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "perfect_battery_pct": { "type": "integer", "minimum": 1, "maximum": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" } }, "required": [ "price_table" ], "additionalProperties": false, "description": "Trade-in buy table («parte de pago»), for a business that buys used devices: `price_table` rows `{model, top, used, min_battery_pct?, low_battery_factor?, direct_purchase?}` (`top` = max paid for a flawless unit, `used` = with normal wear, whole currency units; capacity does not change the value; `min_battery_pct` = a known battery under it is not bought; `low_battery_factor` (0–1) = a known battery under `perfect_battery_pct` caps the price at `used × low_battery_factor` instead of `used`; `direct_purchase: false` = the model is taken only as part of the payment for another item, never bought outright — absent = true), `not_bought` (models never bought), `floor_factor` (0–1, default 0.7: the low end for a unit with issues or unknown condition is `used × floor_factor`), `perfect_floor_factor` (0–1, default 0.85: the low end for a flawless unit is `used × perfect_floor_factor`, its high end is `top`), `rounding` (default 10000), `perfect_battery_pct` (default 90), `currency` (default CLP). On an ecommerce workspace its presence offers the agents the `estimate_trade_in` tool (a wide range of what the customer would still pay) and the `quote_buyback` tool (the most paid for one device sold outright, or the discount for a `direct_purchase: false` model); the business’s own site reads it at `GET /storefront/trade-in`. Replaced whole on write; `null` clears it." }, "ads": { "type": "object", "properties": { "tag_choice": { "type": [ "string", "null" ], "enum": [ "site", "no_site" ] }, "goal": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "outcomes", "value", "roas" ], "description": "`outcomes` = results from ads this month; `value` = attributed value (CLP); `roas` = return (×)." }, "target": { "type": "number", "exclusiveMinimum": 0, "description": "The month’s target. `roas` ≤ 100; `value` ≤ 10^10; `outcomes` ≤ 10^6." }, "period": { "type": "string", "enum": [ "month" ], "description": "The only period: the calendar month." } }, "required": [ "kind", "target", "period" ], "additionalProperties": false }, "dismissed_actions": { "type": "object", "additionalProperties": { "type": [ "string", "null" ], "format": "date-time" } }, "specialty_map": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "match": { "type": "string", "minLength": 1, "maxLength": 120, "description": "A fragment of the campaign, ad-set or ad name (accent- and case-insensitive)." }, "especialidad": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The roster specialty it books (e.g. «TTM»)." }, "professional_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 20, "description": "The vendor professional ids (`clinic_professional.external_id`) it books with." }, "visit_minutes": { "type": "integer", "minimum": 5, "maximum": 480, "description": "How long the entry visit (the evaluation) takes." }, "evaluation_price": { "type": "integer", "minimum": 0, "maximum": 100000000, "description": "What the entry visit costs (CLP)." } }, "required": [ "match" ], "additionalProperties": false }, "maxItems": 50 } }, "additionalProperties": false, "description": "Vitrina Ads workspace choices. `tag_choice`: how the «Instalar el tag» step was answered — `site` (the tag goes on the workspace's website, pasted or through Google Tag Manager) or `no_site` (no website; step skipped on purpose); `null` clears it. `goal`: the monthly goal the Ads hero measures pace against (`{kind, target, period:'month'}`; `null` clears it — `PUT /ads/goal` is the dedicated door). `dismissed_actions`: `{ [action id]: until ISO }` merged onto the stored map (`null` removes an id; expired entries are pruned). `specialty_map`: which specialty (and professionals, entry-visit length and price) each campaign / ad set / ad books — the agenda-capacity check behind «Pausar» / «Subir» reads it before the name match; replaces the stored list whole (`null` clears it). Merged into the stored `ads` object; the server stamps `tag_choice_at` / `goal_at` / `goal_by` on every write, and `GET /tenant/settings` returns them under `ads`." }, "voice": { "type": [ "object", "null" ], "properties": { "brand_name": { "type": "string", "minLength": 1, "maxLength": 60, "pattern": "^[^{}\\r\\n\\t]+$", "description": "Brand name templates say literally (\"te escribimos de Automec\"). Absent = the workspace name." }, "register": { "type": "string", "enum": [ "tu", "usted" ], "description": "How templates address people. Absent = `usted` for healthcare, `tu` otherwise." }, "opening_marks": { "type": "string", "enum": [ "none", "keep" ], "description": "«Signos de apertura» in the AI's chat replies and follow-ups. `none` (default when absent): no opening «¿» «¡», the way people type in a Chilean chat; removed at send time from every AI message. `keep`: the agent writes them. An agent can override it (`behavior_policies.opening_marks`)." }, "agent_register": { "type": "string", "enum": [ "tu", "usted", "mirror" ], "description": "«Trato» of the AI agents: `tu`, `usted`, or `mirror` (tú until the customer uses usted). Absent: each agent's own instructions decide. Wins over the agent's instructions; an agent can override it (`behavior_policies.register`)." } }, "additionalProperties": false }, "agent_language": { "type": "object", "properties": { "banned_terms": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 60, "pattern": "^[^\\r\\n\\t]+$" }, "maxItems": 100, "description": "Words the AI agent must never write to customers (case- and accent-insensitive, whole words), merged with the platform es-CL list. A reply that uses one is rewritten without it before it is sent. Up to 100 terms of 2 to 60 characters." } }, "additionalProperties": false }, "notifications": { "type": "object", "properties": { "staff_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" } } }, "unanswered_supervisor_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" }, "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "delay_minutes": { "type": "integer", "minimum": 5, "maximum": 1440, "description": "Minutes of open time a conversation waits on the team before the supervisors get the WhatsApp, once per episode. Unset = 60." } } }, "reminder_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" } }, "description": "Staff WhatsApp on every «sin respuesta» reminder, to the assignee (template aviso_sigue_esperando_v1). Opt-in: each send costs a WhatsApp conversation." }, "booking_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" }, "change_template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" } } }, "visit_watchers_whatsapp": { "type": "object", "properties": { "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 5 } }, "required": [ "user_ids" ] }, "finanzas_whatsapp": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "account_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$" }, "template_language": { "type": "string", "maxLength": 16, "pattern": "^[A-Za-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})?$" }, "digest_template_name": { "type": "string", "maxLength": 512, "pattern": "^[a-z0-9_]+$", "description": "The weekly Finanzas digest template (resumen_finanzas_semanal_v1), wired on approval." } } }, "stock_alert": { "type": "object", "properties": { "stage_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "description": "Lead stages that trigger the «Stock faltante» check when a lead moves into them. Empty turns it off." } }, "required": [ "stage_ids" ] } } }, "manage_workshop": { "type": "boolean", "description": "Turn the «Servicio de vehículos» workshop board on (creates it; automotive only) or off (removes it only while it never held a ticket)." } } }, "LiveUsage": { "type": "object", "properties": { "as_of": { "type": "string" }, "period": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`, America/Santiago." }, "start": { "type": "string" }, "end": { "type": "string" }, "elapsed_days": { "type": "integer" }, "total_days": { "type": "integer" }, "closed": { "type": "boolean", "description": "The Santiago month has ended (a past `period`)." } }, "required": [ "month", "start", "end", "elapsed_days", "total_days", "closed" ] }, "mode": { "type": "string", "enum": [ "metered", "fixed_contract", "not_billed", "complimentary", "billing_not_started", "external_month", "clinic_plan" ], "description": "`metered`: rate card. `fixed_contract`: one fixed monthly price, usage shown at $0. `not_billed`: usage only, no prices. `complimentary`: never billed («se calcula, no se cobra») but priced exactly like `metered` for reference — lines, totals, projection and UF, `show_prices` true, `next_charge` null; show the amounts with a note that the workspace is not charged. `billing_not_started`: billing begins on `billing_starts_on`. `external_month`: the month is invoiced outside the system. `clinic_plan`: billed on the plan anniversary, not by this view." }, "billing_starts_on": { "type": [ "string", "null" ] }, "show_prices": { "type": "boolean", "description": "False: render usage only, no amounts anywhere. True for `complimentary` too: show the amounts, but as a reference (never charged)." }, "uf": { "type": [ "object", "null" ], "properties": { "clp": { "type": "number" }, "date": { "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "clp", "date", "stale" ], "description": "Today's UF, for the CLP estimate only (the close freezes its own)." }, "usage": { "type": "object", "properties": { "conversations": { "type": "integer" }, "voice_minutes": { "type": "integer" }, "forwarded_voice_minutes": { "type": "integer" }, "eval_runs": { "type": "integer", "description": "Completed agent-eval runs billed this month (queued after an admin accepted the per-run price)." }, "email_marketable_contacts": { "type": "integer" }, "email_marketing_sent": { "type": "integer", "description": "Email-campaign messages sent this month; the contact-base line is billed only when above 0." } }, "required": [ "conversations", "voice_minutes", "forwarded_voice_minutes", "eval_runs", "email_marketable_contacts", "email_marketing_sent" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "conversations", "email_contacts", "voice_minutes", "forwarded_voice_minutes", "eval_runs", "addon_flat", "quota_overage", "contract_fixed", "conversation_credit", "manual_credit" ] }, "count": { "type": "number" }, "uf_unit": { "type": [ "number", "null" ] }, "uf_subtotal": { "type": [ "number", "null" ] }, "clp_amount": { "type": "integer" }, "included_in_contract": { "type": "boolean" }, "feature": { "type": "string" }, "active_fraction": { "type": "number" }, "complimentary": { "type": "boolean", "description": "An add-on granted free: shown at 0 («Incluido sin costo»)." }, "clp_month": { "type": "integer", "description": "A peso-priced flat add-on (`flatClpMonth`): its monthly list price in whole CLP, neto. Display only; the line bills `uf_subtotal`." } }, "required": [ "kind", "count", "uf_unit", "uf_subtotal" ] } }, "totals": { "type": [ "object", "null" ], "properties": { "subtotal_uf": { "type": "number" }, "clp_net": { "type": "integer" }, "iva_amount": { "type": "integer" }, "clp_total": { "type": "integer" } }, "required": [ "subtotal_uf", "clp_net", "iva_amount", "clp_total" ] }, "projection": { "type": [ "object", "null" ], "properties": { "basis": { "type": "string", "enum": [ "linear_elapsed_days" ] }, "elapsed_days": { "type": "integer" }, "total_days": { "type": "integer" }, "conversations": { "type": "integer" }, "voice_minutes": { "type": "integer" }, "forwarded_voice_minutes": { "type": "integer" }, "eval_runs": { "type": "integer" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "conversations", "email_contacts", "voice_minutes", "forwarded_voice_minutes", "eval_runs", "addon_flat", "quota_overage", "contract_fixed", "conversation_credit", "manual_credit" ] }, "count": { "type": "number" }, "uf_unit": { "type": [ "number", "null" ] }, "uf_subtotal": { "type": [ "number", "null" ] }, "clp_amount": { "type": "integer" }, "included_in_contract": { "type": "boolean" }, "feature": { "type": "string" }, "active_fraction": { "type": "number" }, "complimentary": { "type": "boolean", "description": "An add-on granted free: shown at 0 («Incluido sin costo»)." }, "clp_month": { "type": "integer", "description": "A peso-priced flat add-on (`flatClpMonth`): its monthly list price in whole CLP, neto. Display only; the line bills `uf_subtotal`." } }, "required": [ "kind", "count", "uf_unit", "uf_subtotal" ] } }, "totals": { "type": [ "object", "null" ], "properties": { "subtotal_uf": { "type": "number" }, "clp_net": { "type": "integer" }, "iva_amount": { "type": "integer" }, "clp_total": { "type": "integer" } }, "required": [ "subtotal_uf", "clp_net", "iva_amount", "clp_total" ] } }, "required": [ "basis", "elapsed_days", "total_days", "conversations", "voice_minutes", "forwarded_voice_minutes", "eval_runs", "lines", "totals" ], "description": "An ESTIMATE: month-to-date usage scaled linearly by the share of the Santiago month elapsed. `null` when prices are hidden." }, "next_charge": { "type": [ "object", "null" ], "properties": { "period_label": { "type": [ "string", "null" ], "description": "«1 – 31 oct 2026»." }, "cutoff_date": { "type": [ "string", "null" ], "description": "Last Santiago day the cobro covers (`YYYY-MM-DD`)." }, "issue_date": { "type": "string", "description": "Santiago day the close issues the cobro (the 1st)." }, "charge_date": { "type": "string", "description": "Santiago day it is charged (`collection: automatic`) or falls due for a transfer — the `due_at` the close would stamp today." }, "charge_date_label": { "type": [ "string", "null" ], "description": "«1 nov 2026»." }, "collection": { "type": "string", "enum": [ "automatic", "transfer" ], "description": "`automatic` while a payment method is active; otherwise the cobro is paid by transfer within a 3-business-day term." }, "method_state": { "type": "string", "enum": [ "active", "pending", "failed", "revoked", "none" ], "description": "`pending`: enrolment not confirmed yet (paid by transfer until it is)." }, "method": { "type": [ "object", "null" ], "properties": { "provider": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "bank_name": { "type": [ "string", "null" ] }, "account_last4": { "type": [ "string", "null" ] }, "card_brand": { "type": [ "string", "null" ] }, "card_last4": { "type": [ "string", "null" ] } }, "required": [ "provider", "status" ] }, "method_label": { "type": [ "string", "null" ], "description": "«tu cuenta corriente BancoEstado ••1234», as the cobro names it; only while active." }, "transfer_available": { "type": "boolean", "description": "True when Vitrina's transfer account is configured." }, "uf_value": { "type": [ "number", "null" ], "description": "Today's UF (an estimate: the close freezes its own day's UF)." }, "uf_value_date": { "type": [ "string", "null" ] }, "so_far": { "type": [ "object", "null" ], "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "uf_unit": { "type": [ "number", "null" ] }, "uf_subtotal": { "type": "number" }, "clp_unit": { "type": [ "number", "null" ], "description": "Unit price in pesos at the invoice’s UF value, to the centavo (`uf_unit × uf_value`) — display only; the line’s pesos are `clp_subtotal`." }, "clp_amount": { "type": [ "integer", "null" ] }, "clp_subtotal": { "type": [ "integer", "null" ], "description": "The line's net pesos as the cobro prints it; the lines add up exactly to `clp_net`. 0 for an included line; null without a UF value." }, "included": { "type": [ "string", "null" ], "enum": [ "contract", "complimentary" ] }, "conversation_ref": { "type": [ "string", "null" ], "description": "Credit lines: the credited conversation (`C-1042`)." }, "reason": { "type": [ "string", "null" ], "description": "Credit lines: why the conversation was exempted." }, "source_invoice_number": { "type": [ "string", "null" ], "description": "Credit lines: the invoice that billed it originally." }, "source_dte_folio": { "type": [ "string", "null" ], "description": "Credit lines: the folio of the factura that invoice already had, when it had one." } }, "required": [ "kind", "label", "detail", "quantity", "uf_unit", "uf_subtotal", "clp_amount", "included" ] } }, "uf_subtotal": { "type": "number" }, "clp_net": { "type": "integer" }, "iva_amount": { "type": "integer", "description": "round(clp_net × 0.19), the rounding the close uses." }, "clp_total": { "type": "integer" } }, "required": [ "lines", "uf_subtotal", "clp_net", "iva_amount", "clp_total" ], "description": "The month so far, priced as the close would price it now." }, "estimate": { "type": [ "object", "null" ], "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "uf_unit": { "type": [ "number", "null" ] }, "uf_subtotal": { "type": "number" }, "clp_unit": { "type": [ "number", "null" ], "description": "Unit price in pesos at the invoice’s UF value, to the centavo (`uf_unit × uf_value`) — display only; the line’s pesos are `clp_subtotal`." }, "clp_amount": { "type": [ "integer", "null" ] }, "clp_subtotal": { "type": [ "integer", "null" ], "description": "The line's net pesos as the cobro prints it; the lines add up exactly to `clp_net`. 0 for an included line; null without a UF value." }, "included": { "type": [ "string", "null" ], "enum": [ "contract", "complimentary" ] }, "conversation_ref": { "type": [ "string", "null" ], "description": "Credit lines: the credited conversation (`C-1042`)." }, "reason": { "type": [ "string", "null" ], "description": "Credit lines: why the conversation was exempted." }, "source_invoice_number": { "type": [ "string", "null" ], "description": "Credit lines: the invoice that billed it originally." }, "source_dte_folio": { "type": [ "string", "null" ], "description": "Credit lines: the folio of the factura that invoice already had, when it had one." } }, "required": [ "kind", "label", "detail", "quantity", "uf_unit", "uf_subtotal", "clp_amount", "included" ] } }, "uf_subtotal": { "type": "number" }, "clp_net": { "type": "integer" }, "iva_amount": { "type": "integer", "description": "round(clp_net × 0.19), the rounding the close uses." }, "clp_total": { "type": "integer" } }, "required": [ "lines", "uf_subtotal", "clp_net", "iva_amount", "clp_total" ], "description": "The month-end estimate (linear by elapsed days): what is likely charged." } }, "required": [ "period_label", "cutoff_date", "issue_date", "charge_date", "charge_date_label", "collection", "method_state", "method", "method_label", "transfer_available", "uf_value", "uf_value_date", "so_far", "estimate" ], "description": "The cobro the close of this month will issue: dates, how it is collected, and its lines in pesos so far and at month end, built like the hosted cobro. `null` when prices are hidden." }, "addons": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "canceled", "suspended" ] }, "included_reason": { "type": [ "string", "null" ], "enum": [ "complimentary", "contract", "not_billed", "partner", "waiver" ] }, "waiver_until": { "type": [ "string", "null" ] } }, "required": [ "feature", "status", "included_reason", "waiver_until" ] } }, "amount_source": { "type": "string", "enum": [ "estimate", "invoice", "external", "none" ], "description": "Where `lines`/`totals` come from. `estimate`: the open month priced at today's UF, or a closed `complimentary` month priced on the rate card at its close day's UF (reference only). `invoice`: the issued cobro, exactly as frozen at the close (never recomputed); a cobro issued by hand for the month reads the same, with its totals. `external`: the month was invoiced by hand outside the system and its amount is not on this month (no cobro on record, or it was billed on a cobro listed on another month — then `invoice` names that cobro). `none`: nothing was billed or prices are hidden — usage only." }, "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string" }, "issued_at": { "type": "string" } }, "required": [ "id", "number", "status", "issued_at" ], "description": "A closed month's issued cobro — for a hand-billed month billed on another month's cobro, that cobro; `null` otherwise." }, "conversations_source": { "type": "string", "enum": [ "invoice", "live" ], "description": "`invoice`: conversations counted from the set the cobro froze at the close (reconciles with it exactly); `live`: from the meter." }, "daily": { "type": "object", "properties": { "days": { "type": "array", "items": { "type": "string" }, "description": "`YYYY-MM-DD` (America/Santiago): every day of a closed month; day 1 to today for the open month." }, "series": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "conversations", "voice_minutes", "forwarded_voice_minutes", "eval_runs", "email_marketing_sent", "addon_usage" ] }, "feature": { "type": [ "string", "null" ], "description": "`addon_usage` only: the add-on feature key." }, "total": { "type": "integer", "description": "Σ `values`." }, "values": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `days`." } }, "required": [ "metric", "feature", "total", "values" ] } } }, "required": [ "days", "series" ], "description": "The month’s meters per day. Counts only, never content." }, "history": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`." }, "source": { "type": "string", "enum": [ "invoice", "external" ] }, "invoice_id": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "uf_subtotal": { "type": [ "number", "null" ] }, "clp_net": { "type": [ "integer", "null" ] }, "iva_amount": { "type": [ "integer", "null" ] }, "clp_total": { "type": [ "integer", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "conversations", "email_contacts", "voice_minutes", "forwarded_voice_minutes", "eval_runs", "addon_flat", "quota_overage", "contract_fixed", "conversation_credit", "manual_credit" ] }, "count": { "type": "number" }, "uf_unit": { "type": [ "number", "null" ] }, "uf_subtotal": { "type": [ "number", "null" ] }, "clp_amount": { "type": "integer" }, "included_in_contract": { "type": "boolean" }, "feature": { "type": "string" }, "active_fraction": { "type": "number" }, "complimentary": { "type": "boolean", "description": "An add-on granted free: shown at 0 («Incluido sin costo»)." }, "clp_month": { "type": "integer", "description": "A peso-priced flat add-on (`flatClpMonth`): its monthly list price in whole CLP, neto. Display only; the line bills `uf_subtotal`." } }, "required": [ "kind", "count", "uf_unit", "uf_subtotal" ] } } }, "required": [ "month", "source", "invoice_id", "number", "status", "issued_at", "uf_subtotal", "clp_net", "iva_amount", "clp_total", "lines" ] } } }, "required": [ "as_of", "period", "mode", "billing_starts_on", "show_prices", "uf", "usage", "lines", "totals", "projection", "next_charge", "addons", "amount_source", "invoice", "conversations_source", "daily", "history" ] }, "ConversationDispute": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "approved", "rejected" ] }, "reason_code": { "type": "string", "enum": [ "not_real_customer", "duplicate", "answered_by_human", "other" ] }, "reason_label": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "resolution": { "type": [ "string", "null" ], "enum": [ "credit", "refund" ], "description": "Approved only: `credit` = discounted on the next invoice, `refund` = paid back." }, "resolution_note": { "type": [ "string", "null" ], "description": "Rejected only: why it was rejected." }, "created_at": { "type": "string" }, "resolved_at": { "type": [ "string", "null" ] } }, "required": [ "id", "conversation_id", "status", "reason_code", "reason_label", "comment", "resolution", "resolution_note", "created_at", "resolved_at" ], "description": "The latest «Reportar» of this conversation, if any (#3610)." }, "BilledConversationsPage": { "type": "object", "properties": { "period": { "type": "object", "properties": { "month": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "closed": { "type": "boolean" }, "source": { "type": "string", "enum": [ "invoice", "live" ], "description": "`invoice` = the set the invoice froze at the close; `live` = the meter now." } }, "required": [ "month", "start", "end", "closed", "source" ] }, "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "issued_at": { "type": "string" } }, "required": [ "id", "number", "status", "issued_at" ] }, "summary": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 }, "unreviewed": { "type": "integer", "minimum": 0 }, "exempted_after_close": { "type": "integer", "minimum": 0 }, "conversations_uf": { "type": "number", "minimum": 0 } }, "required": [ "count", "unreviewed", "exempted_after_close", "conversations_uf" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "display_id": { "type": [ "string", "null" ], "description": "Human id, e.g. `C-3052`." }, "first_billable_at": { "type": "string", "description": "The billable moment: the first agent reply that reached a customer who wrote." }, "channel": { "type": [ "string", "null" ] }, "contact_last4": { "type": [ "string", "null" ], "description": "Last 4 digits of the contact’s phone; the full number is never returned." }, "review_state": { "type": "string", "enum": [ "billable", "unreviewed" ], "description": "Review verdict at the close (or now, for the open month). `unreviewed` bills (policy)." }, "counted_because": { "type": "string", "enum": [ "customer_wrote_agent_replied" ] }, "dispute": { "$ref": "#/components/schemas/ConversationDispute" }, "exempted_after_close": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "exempted_at": { "type": [ "string", "null" ] }, "credited_on_invoice": { "type": [ "string", "null" ] } }, "required": [ "reason", "exempted_at", "credited_on_invoice" ], "description": "Set when a review exempted it after its invoice was issued; it is then credited on a later invoice." } }, "required": [ "conversation_id", "display_id", "first_billable_at", "channel", "contact_last4", "review_state", "counted_because", "exempted_after_close" ] } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "period", "invoice", "summary", "items", "next_cursor" ] }, "ClaimComprobante": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "invoice_id": { "type": "string", "format": "uuid", "description": "The Cobro the claim is on." }, "claimed_at": { "type": "string", "description": "ISO instant of the «Ya pagué» this file belongs to." }, "filename": { "type": "string", "description": "Display name (sanitised: spaces and accents become `_`)." }, "mime": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/png" ] }, "size_bytes": { "type": "integer" }, "uploaded_at": { "type": "string" }, "state": { "type": "string", "enum": [ "pending", "confirmed", "rejected", "closed" ], "description": "`pending`: the claim waits for Vitrina (the file can still be replaced). `confirmed`: Vitrina confirmed the payment; the file stays with it. `rejected`: Vitrina did not find the transfer; kept as history. `closed`: the cobro was paid another way while the claim waited." }, "rejected_at": { "type": [ "string", "null" ] }, "received_payment_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The «Pago recibido» a confirmed claim became (it carries this file)." } }, "required": [ "id", "invoice_id", "claimed_at", "filename", "mime", "size_bytes", "uploaded_at", "state", "rejected_at", "received_payment_id" ], "description": "#7094: the file attached to this claim («comprobante adjunto»), or null." }, "BillingHistoryRow": { "type": "object", "properties": { "row_key": { "type": "string", "description": "Stable, unique row key (list key / cursor anchor): the invoice id, or `manual:YYYY-MM`. Not a resource id — use `invoice_id`." }, "kind": { "type": "string", "enum": [ "invoice", "manual" ], "description": "`invoice` = a cobro issued by Vitrina; `manual` = a month invoiced outside the system." }, "period": { "type": "string", "description": "Billing month, `YYYY-MM` (America/Santiago)." }, "invoice_id": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ], "description": "The cobro number. Null for a manual month without one." }, "status": { "type": "string", "enum": [ "pending", "overdue", "paid", "void", "billed_outside" ], "description": "`billed_outside` = a month invoiced by hand with no cobro on record («Facturado por correo»). A hand-billed month whose cobro is on record reads that cobro’s status." }, "clp_net": { "type": [ "integer", "null" ] }, "iva_amount": { "type": [ "integer", "null" ] }, "clp_total": { "type": [ "integer", "null" ] }, "issued_at": { "type": [ "string", "null" ] }, "due_date": { "type": [ "string", "null" ], "description": "Santiago `YYYY-MM-DD`." }, "paid_at": { "type": [ "string", "null" ] }, "paid_date": { "type": [ "string", "null" ], "description": "Santiago `YYYY-MM-DD` of `paid_at`." }, "conversation_count": { "type": "integer", "description": "Conversations of the month: the set the cobro froze at the close, else the live meter — the same count `GET /billing/conversations?period=` reports." }, "payable": { "type": "boolean", "description": "True when «Pagar» applies: an unpaid cobro whose charge is not in flight (`POST /billing/invoices/{id}/pay`)." }, "billed_in": { "type": [ "object", "null" ], "properties": { "invoice_id": { "type": "string" }, "number": { "type": "string" }, "period": { "type": "string", "description": "`YYYY-MM` of the row that carries the cobro." } }, "required": [ "invoice_id", "number", "period" ], "description": "A month invoiced by hand that was billed on a cobro listed on another month (one cobro for two months): that cobro. The amount is on the cobro’s own row, never repeated here. Null otherwise." }, "concept": { "type": [ "string", "null" ], "description": "What a cobro billed only with one-time charges was for (their labels, e.g. «Implementación de Vitrina»), so the row does not read as a usage month. Null for a usage month or a month invoiced by hand." }, "documents": { "type": "object", "properties": { "cobro_pdf_path": { "type": [ "string", "null" ], "description": "API path of the cobro PDF (`GET /billing/invoices/{id}/pdf`)." }, "factura_state": { "type": "string", "enum": [ "issued", "after_payment", "processing", "none" ], "description": "`issued` (folio, PDF and XML available), `after_payment` (unpaid: the factura is emitted once paid), `processing` (paid, emission in flight), `none` (void or manual month)." }, "factura": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string", "enum": [ "factura", "boleta" ], "description": "Which tax document this month carries." }, "folio": { "type": "string" }, "pdf_path": { "type": "string" }, "xml_path": { "type": "string" } }, "required": [ "kind", "folio", "pdf_path", "xml_path" ] } }, "required": [ "cobro_pdf_path", "factura_state", "factura" ] } }, "required": [ "row_key", "kind", "period", "invoice_id", "number", "status", "clp_net", "iva_amount", "clp_total", "issued_at", "due_date", "paid_at", "paid_date", "conversation_count", "payable", "billed_in", "concept", "documents" ] }, "BillingHistoryPage": { "type": "object", "properties": { "filter": { "type": "string", "enum": [ "all", "paid", "open" ], "description": "`all` (default), `paid` (Pagadas) or `open` (Pendientes: por pagar or vencido)." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BillingHistoryRow" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "filter", "items", "next_cursor" ] }, "BillingProfile": { "type": "object", "properties": { "legal_name": { "type": [ "string", "null" ] }, "rut": { "type": [ "string", "null" ] }, "giro": { "type": [ "string", "null" ] }, "address": { "type": "object", "properties": { "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "comuna_code": { "type": [ "string", "null" ] } }, "required": [ "line1", "line2", "city", "region", "postal_code", "country", "comuna_code" ] }, "billing_email": { "type": [ "string", "null" ] }, "cc_emails": { "type": "array", "items": { "type": "string" } }, "billing_emails": { "type": "array", "items": { "type": "string" }, "description": "Every address that receives the billing emails, in order: `billing_email` first, then `cc_emails`. All are recipients (to), none is a mere copy." }, "complete": { "type": "boolean", "description": "True when a factura electrónica can be issued with this data." }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "rut", "legal_name", "giro", "address_street", "comuna", "billing_email" ] }, "description": "Required fields still missing; empty when `complete`." }, "source": { "type": [ "string", "null" ], "enum": [ "in_app", "import", "migrated" ], "description": "in_app = saved in the app; import = Tally/Contratos import; migrated = copied from older records." }, "confirmed_at": { "type": [ "string", "null" ], "description": "When the client confirmed the data: saved in the app (source in_app), or typed into the onboarding form (source import, the import time). Null = migrated data nobody has reviewed. Whether a factura can be issued is `complete`, not this." } }, "required": [ "legal_name", "rut", "giro", "address", "billing_email", "cc_emails", "billing_emails", "complete", "missing", "source", "confirmed_at" ] }, "PaymentMethodSetup": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "fintoc", "mercadopago", "transbank_oneclick" ] }, "status": { "type": "string", "enum": [ "pending", "active" ] }, "mandateId": { "type": "string" }, "setupUrl": { "type": [ "string", "null" ], "format": "uri" }, "setupToken": { "type": [ "string", "null" ], "description": "Transbank Oneclick only: send the browser to `setupUrl` with a form POST carrying this value as the `TBK_TOKEN` field." } }, "required": [ "provider", "status", "mandateId", "setupUrl" ] }, "PaymentMethodStatus": { "type": "object", "properties": { "provider": { "type": [ "string", "null" ], "enum": [ "fintoc", "mercadopago", "transbank_oneclick" ] }, "status": { "type": [ "string", "null" ], "enum": [ "pending", "active", "revoked", "failed" ] }, "mandateId": { "type": [ "string", "null" ] }, "card": { "type": [ "object", "null" ], "properties": { "brand": { "type": [ "string", "null" ] }, "last4": { "type": "string" } }, "required": [ "brand", "last4" ], "description": "The saved card of the active mandate (Transbank Oneclick): brand and last four digits only." }, "bankAccount": { "type": [ "object", "null" ], "properties": { "bankName": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] } }, "required": [ "bankName", "last4" ], "description": "The debited account of the active PAC mandate (Fintoc): bank name and last digits only." }, "pacBanks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "description": "Banks where a PAC (automatic debit from a current account) can be enrolled through Fintoc. A client whose bank is not listed pays by card (when offered) or by transfer." }, "availableProviders": { "type": "array", "items": { "type": "string", "enum": [ "fintoc", "mercadopago", "transbank_oneclick" ] }, "description": "Providers that can be enrolled right now. `transbank_oneclick` appears only once Vitrina has its card contract configured." } }, "required": [ "provider", "status", "mandateId" ] }, "PaymentMethodItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rail": { "type": "string", "enum": [ "fintoc_pac", "fintoc_card", "oneclick", "mercadopago" ], "description": "The rail that holds the method: `fintoc_pac` (automatic debit from a current account through Fintoc), `fintoc_card` (credit or debit card on file at Fintoc), `oneclick` (card on file at Transbank Webpay Oneclick), `mercadopago` (card on file at Mercado Pago)." }, "rail_name": { "type": "string", "description": "The rail by its own name, ready to print («Tarjeta (Webpay Oneclick)»)." }, "status": { "type": "string", "enum": [ "activo", "pendiente_firma", "rechazado" ], "description": "`activo` = billable. A PAC can also be `pendiente_firma` (the owner has not signed the bank mandate yet) or `rechazado` (the bank rejected it)." }, "is_default": { "type": "boolean", "description": "The method the cobros are charged to («Predeterminado»)." }, "bank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] } }, "required": [ "name", "last4" ], "description": "PAC only: the debited bank and the account’s last digits." }, "card": { "type": [ "object", "null" ], "properties": { "brand": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] }, "exp_month": { "type": [ "integer", "null" ] }, "exp_year": { "type": [ "integer", "null" ] }, "kind": { "type": [ "string", "null" ], "enum": [ "credit", "debit", "prepaid" ], "description": "Credit, debit or prepaid, when the rail reports it (Fintoc)." } }, "required": [ "brand", "last4", "exp_month", "exp_year" ], "description": "Cards only: brand, last four digits, expiry and kind. Transbank Oneclick does not report the expiry, so it is null there." }, "removable": { "type": "boolean", "description": "False for the default method while a cobro is pending, and while a charge is in progress on the method." }, "created_at": { "type": "string" } }, "required": [ "id", "rail", "rail_name", "status", "is_default", "bank", "card", "removable", "created_at" ] }, "PaymentMethodsView": { "type": "object", "properties": { "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethodItem" }, "description": "The default first, then newest first. Removed methods are not listed." }, "default_method_id": { "type": [ "string", "null" ], "format": "uuid" }, "pays_by": { "type": "string", "enum": [ "method", "transfer" ], "description": "`transfer` when there is no active method: the cobros are paid by bank transfer." }, "pending_cobro": { "type": [ "object", "null" ], "properties": { "invoice_id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "reference": { "type": [ "string", "null" ], "description": "The reference to write in a transfer comment («VT-7K2QM9»)." }, "due_at": { "type": [ "string", "null" ] } }, "required": [ "invoice_id", "number", "reference", "due_at" ], "description": "The oldest cobro still owed (issued, being charged or past due), or null." }, "transfer": { "type": [ "object", "null" ], "properties": { "account": { "type": [ "object", "null" ], "properties": { "bank": { "type": "string" }, "account_type": { "type": [ "string", "null" ] }, "account_number": { "type": "string" }, "holder_name": { "type": "string" }, "holder_rut": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "bank", "account_type", "account_number", "holder_name", "holder_rut", "email" ], "description": "Vitrina’s account; null while it is not configured." }, "reference": { "type": [ "string", "null" ], "description": "The reference of the cobro to pay; null when nothing is owed (each cobro carries its own)." }, "invoice_number": { "type": [ "string", "null" ] } }, "required": [ "account", "reference", "invoice_number" ], "description": "Set only when `pays_by` is `transfer`." }, "available_rails": { "type": "array", "items": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "fintoc_pac", "fintoc_card", "oneclick", "mercadopago" ], "description": "The rail that holds the method: `fintoc_pac` (automatic debit from a current account through Fintoc), `fintoc_card` (credit or debit card on file at Fintoc), `oneclick` (card on file at Transbank Webpay Oneclick), `mercadopago` (card on file at Mercado Pago)." }, "rail_name": { "type": "string" }, "recommended": { "type": "boolean" }, "warning": { "type": [ "string", "null" ], "description": "Text to show on the setup screen before continuing; set for `fintoc_pac` (company accounts fail), null otherwise." } }, "required": [ "rail", "rail_name", "recommended", "warning" ] }, "description": "Rails that can be added now, card rails most preferred first and the PAC last: `fintoc_card` appears only while Fintoc has the product enabled for Vitrina (probed, no flag) and, while it does, `oneclick` and `mercadopago` are not listed; without it they stay as the card fallback. `fintoc_pac` only with «PAC permitido» on and Fintoc PAC available. `recommended` is the first card rail; the PAC is never recommended." }, "pac_banks": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] }, "description": "Banks where a PAC can be enrolled; send a `code` as `bank` when adding a PAC." } }, "required": [ "methods", "default_method_id", "pays_by", "pending_cobro", "transfer", "available_rails", "pac_banks" ] }, "ClinicProfessional": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "native", "healthatom", "reservo" ] }, "external_id": { "type": [ "string", "null" ] }, "nombre": { "type": "string" }, "apellidos": { "type": "string" }, "rut": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "especialidad": { "type": [ "string", "null" ] }, "especialidades_secundarias": { "type": "array", "items": { "type": "string" } }, "cargo": { "type": [ "string", "null" ] }, "registro": { "type": [ "string", "null" ] }, "sexo": { "type": [ "string", "null" ] }, "birthdate": { "type": [ "string", "null" ] }, "direccion": { "type": [ "string", "null" ] }, "agenda_online": { "type": "boolean" }, "intervalo_minutes": { "type": [ "number", "null" ] }, "active": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "charges_with": { "type": [ "string", "null" ], "enum": [ "company_invoice", "fee_receipt" ], "description": "«Cobra con» — how the professional charges the clinic for her liquidación: `company_invoice` = factura de su sociedad (then `company_legal_name` and a check-digit-valid `company_rut` are required), `fee_receipt` = boleta de honorarios (the liquidación then shows the SII retención of the boleta’s year and the líquido). Null = not recorded. Vitrina-owned: editable on any source; switching away from `company_invoice` clears the sociedad." }, "company_legal_name": { "type": [ "string", "null" ] }, "company_rut": { "type": [ "string", "null" ] }, "user_id": { "type": [ "string", "null" ] }, "schedule": { "type": [ "object", "null" ], "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "inicio": { "type": "string" }, "fin": { "type": "string" } }, "required": [ "inicio", "fin" ] } } }, "synced_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "source", "external_id", "nombre", "apellidos", "rut", "email", "phone", "especialidad", "especialidades_secundarias", "cargo", "registro", "sexo", "birthdate", "direccion", "agenda_online", "intervalo_minutes", "active", "description", "charges_with", "company_legal_name", "company_rut", "user_id", "schedule", "synced_at", "created_at", "updated_at" ] }, "ClinicProfessionalDetail": { "allOf": [ { "$ref": "#/components/schemas/ClinicProfessional" }, { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": {} }, "citas_next_7d": { "type": "number" } }, "required": [ "data", "citas_next_7d" ] } ] }, "ClinicService": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "native", "healthatom", "reservo" ] }, "external_id": { "type": [ "string", "null" ] }, "nombre": { "type": "string" }, "codigo": { "type": [ "string", "null" ] }, "categoria": { "type": [ "string", "null" ] }, "tipo": { "type": [ "string", "null" ] }, "precio": { "type": [ "number", "null" ] }, "arancel": { "type": [ "string", "null" ] }, "arancel_external_id": { "type": [ "string", "null" ] }, "arancel_name": { "type": [ "string", "null" ] }, "duration_minutes": { "type": [ "number", "null" ] }, "vendor_duration_minutes": { "type": [ "number", "null" ] }, "review_state": { "type": "string", "enum": [ "stale", "draft", "reviewed" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "is_telehealth": { "type": "boolean" }, "online_bookable": { "type": "boolean" }, "is_entry": { "type": [ "boolean", "null" ] }, "agent_bookable": { "type": [ "boolean", "null" ] }, "agent_bookable_effective": { "type": "boolean" }, "lab_bearing": { "type": "boolean" }, "requires_consent_template_id": { "type": [ "string", "null" ] }, "eligibility_min_age_years": { "type": [ "number", "null" ] }, "eligibility_max_age_years": { "type": [ "number", "null" ] }, "eligibility_sexo": { "type": [ "string", "null" ], "enum": [ "F", "M", "otro" ] }, "eligibility_previsiones": { "type": [ "array", "null" ], "items": { "type": "string" } }, "active": { "type": "boolean" }, "synced_at": { "type": [ "string", "null" ] } }, "required": [ "id", "source", "external_id", "nombre", "codigo", "categoria", "tipo", "precio", "arancel", "arancel_external_id", "arancel_name", "duration_minutes", "vendor_duration_minutes", "review_state", "reviewed_at", "reviewed_by", "is_telehealth", "online_bookable", "is_entry", "agent_bookable", "agent_bookable_effective", "lab_bearing", "requires_consent_template_id", "eligibility_min_age_years", "eligibility_max_age_years", "eligibility_sexo", "eligibility_previsiones", "active", "synced_at" ] }, "ClinicServiceArancel": { "type": "object", "properties": { "external_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": 0 }, "active": { "type": "integer", "minimum": 0 } }, "required": [ "external_id", "name", "total", "active" ] }, "WebhookSubscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "tenant_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "secret": { "type": "string", "description": "The full `whsec_…` secret on the CREATE response only; every other read returns its first nine characters." }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean", "description": "Your own switch. `false` = nothing is delivered." }, "description": { "type": [ "string", "null" ] }, "include_data": { "type": "boolean", "description": "«Incluir datos del recurso»." }, "owner_kind": { "type": [ "string", "null" ], "enum": [ "member", "api_key" ], "description": "Who owns it: the member or API key that created it or last changed its url, events or `include_data`. `null` only on subscriptions created before owners existed (read as the workspace, unrestricted)." }, "owner_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The owner — the member's user id, or the API key id (a personal token acts as its member)." }, "paused_at": { "type": [ "string", "null" ], "description": "Set when the platform AUTO-PAUSED the subscription (20 failed deliveries in a row, or 24 h failing). Paused = nothing is delivered until `POST /webhooks/{id}/resume`." }, "paused_reason": { "type": [ "string", "null" ], "enum": [ "consecutive_failures", "failing_24h" ] }, "last_delivery_at": { "type": [ "string", "null" ] }, "last_status": { "type": [ "integer", "null" ] }, "consecutive_failures": { "type": "integer", "description": "Failed ATTEMPTS in a row (every retry counts). Reset by a success." }, "consecutive_failed_deliveries": { "type": "integer", "description": "Failed DELIVERIES in a row — events whose every retry failed. 20 pauses the subscription. Reset by a success." }, "failing_since": { "type": [ "string", "null" ], "description": "First failed attempt of the current streak; `null` after any success. 24 h pauses the subscription." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "tenant_id", "url", "secret", "events", "enabled", "description", "include_data", "owner_kind", "owner_id", "paused_at", "paused_reason", "last_delivery_at", "last_status", "consecutive_failures", "consecutive_failed_deliveries", "failing_since", "created_at", "updated_at" ] }, "WebhookEventDoc": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "ai_agent.publish", "ai_agent_graph.publish", "agent_scenario_run.completed", "agent_scenario_suite.completed", "conversation.created", "conversation.assigned", "conversation.resolved", "message.received", "message.sent", "ticket.opened", "ticket.reopened", "ticket.resolved", "ticket.closed", "sla.breached", "kb.source.create", "kb.source.embed", "kb.source.update", "kb.source.delete", "kb_file.uploaded", "kb_file.deleted", "skill.created", "skill.updated", "skill.deleted", "custom_tool.created", "custom_tool.updated", "custom_tool.deleted", "macro.applied", "cost.budget_alert", "runtime.budget_exceeded", "lead.created", "lead.stage_changed", "lead.pipeline_changed", "lead.assigned", "lead.won", "lead.lost", "lead.unqualified", "order.created", "order.status_changed", "stock.synced", "stock.source_retired", "vehicle.published", "vehicle.unpublished", "vehicle.publish_failed", "vehicle.created", "vehicle.attachment.created", "mercadolibre.order", "mercadolibre.vis_lead", "chileautos.lead", "yapo.lead", "website.lead", "demo_lead.created", "demo_lead.pending_scheduling", "demo_lead.routed", "demo_booking.booked", "demo_booking.rescheduled", "demo_booking.cancelled", "demo_booking.held", "demo_booking.no_show", "consignment.candidate.created", "quote.issued", "quote.voided", "quote.extended", "quote.archived", "reservation.created", "reservation.voided", "reservation.abono_disposed", "reservation.converted", "sale_note.issued", "sale_note.approved", "sale_note.voided", "purchase_note.issued", "purchase_note.corrected", "purchase_note.voided", "payment.recorded", "consignment.created", "consignment.returned", "consignment.sold", "credit_application.recorded", "credit_application.submitted", "credit_application.decided", "credit_application.withdrawn", "price_approval.requested", "price_approval.decided", "contact.created", "contact.updated", "contact.merged", "appointment.booked", "appointment.rescheduled", "appointment.cancelled", "appointment.completed", "appointment.no_show", "appointment.reminded", "appointment.imported", "campaign.sent", "campaign.paused", "sending_domain.verified", "coach.proposals_ready", "coach.finding_ready", "voice.autonomous_call", "safety_hold.placed", "safety_hold.ack_overdue", "safety_hold.first_response_overdue", "team.created", "team.updated", "team.deleted", "custom_role.created", "custom_role.updated", "custom_role.deleted", "macro.created", "macro.updated", "macro.deleted", "assignment_rule.created", "assignment_rule.updated", "assignment_rule.deleted", "sla_policy.created", "sla_policy.updated", "sla_policy.deleted", "automation_trigger.created", "automation_trigger.updated", "automation_trigger.deleted", "sending_domain.created", "sending_domain.deleted", "whatsapp_template.created", "whatsapp_template.status_changed", "whatsapp_template.deleted", "whatsapp_flow.created", "whatsapp_flow.published", "whatsapp_flow.deprecated", "whatsapp_flow.deleted", "whatsapp_flow.completed", "channel.connected", "channel.updated", "channel.disconnected", "membership.created", "membership.updated", "membership.removed", "clinic_professional.created", "clinic_professional.updated", "clinic_professional.deleted", "clinic_service.created", "clinic_service.updated", "clinic_service.deleted", "clinic_price_list.updated", "clinic_pack_purchase.created", "clinic_pack_purchase.session_consumed", "clinic_pack_purchase.cancelled", "clinic_budget.created", "clinic_budget.sent", "clinic_budget.accepted", "clinic_budget.rejected", "clinic_budget.voided", "clinic_budget.mirror_changed", "clinic_cash_session.opened", "clinic_cash_session.closed", "clinic_patient.created", "clinic_patient.updated", "clinic_patient.deleted", "clinic_patient.merged", "clinic_encounter.opened", "clinic_encounter.closed", "clinic_note.signed", "clinic_note.amended", "clinic_consent.signed", "clinic_consent.revoked", "clinic_document.uploaded", "clinic_document.deleted", "clinic_privacy_request.completed" ] }, "version": { "type": "integer", "description": "The schema version of this event type — every delivery carries it as `version`. Bumped only on a breaking change to `data`." }, "resource_type": { "type": "string", "description": "What the event is about — the `resource.type` of every delivery (`lead`, `vehicle`, `contact`, …)." }, "read_scope": { "type": "string", "description": "The scope a subscription OWNER must hold, with unrestricted visibility, for «Incluir datos del recurso» to deliver `data`. Otherwise the delivery carries `data_omitted`." }, "sensitive": { "type": "boolean", "description": "About a dato sensible (health data): always delivered as the notice, whatever the subscription asked for." }, "description": { "type": "string", "description": "What happened, in a sentence, plus anything a consumer must do about it." }, "fires_when": { "type": "string", "description": "The exact producer condition — so you can reason about ordering and duplicates." }, "data_schema": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Field name → an informal type (\"string (uuid)\", \"integer | null\", \"enum: a|b|c\"). Documentation, not a JSON Schema: the envelope is stable, individual fields may gain siblings." }, "sample": { "type": "object", "additionalProperties": {}, "description": "A realistic `data` object — one delivery body's `data` field." } }, "required": [ "name", "version", "resource_type", "read_scope", "sensitive", "description", "fires_when", "data_schema", "sample" ] }, "WebhookSigningDocs": { "type": "object", "properties": { "envelope": { "type": "object", "additionalProperties": { "type": "string" } }, "data_modes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "The two delivery modes (`notice`, `data`) and every `data_omitted` reason." }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "signature_scheme": { "type": "string" }, "signature_format": { "type": "string" }, "verify_pseudocode": { "type": "array", "items": { "type": "string" } }, "timing_window_seconds": { "type": "integer" }, "retry": { "type": "object", "properties": { "attempts": { "type": "integer" }, "backoff": { "type": "string" }, "delays_seconds": { "type": "array", "items": { "type": "integer" } }, "note": { "type": "string" } }, "required": [ "attempts", "backoff", "delays_seconds", "note" ] }, "auto_pause": { "type": "object", "properties": { "consecutive_failed_deliveries": { "type": "integer" }, "failing_hours": { "type": "integer" }, "note": { "type": "string" } }, "required": [ "consecutive_failed_deliveries", "failing_hours", "note" ] } }, "required": [ "envelope", "data_modes", "headers", "signature_scheme", "signature_format", "verify_pseudocode", "timing_window_seconds", "retry", "auto_pause" ] }, "WebhookEventCatalog": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventDoc" } }, "signing": { "$ref": "#/components/schemas/WebhookSigningDocs" } }, "required": [ "events", "signing" ] }, "CreateWebhookBody": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "*", "ai_agent.publish", "ai_agent_graph.publish", "agent_scenario_run.completed", "agent_scenario_suite.completed", "conversation.created", "conversation.assigned", "conversation.resolved", "message.received", "message.sent", "ticket.opened", "ticket.reopened", "ticket.resolved", "ticket.closed", "sla.breached", "kb.source.create", "kb.source.embed", "kb.source.update", "kb.source.delete", "kb_file.uploaded", "kb_file.deleted", "skill.created", "skill.updated", "skill.deleted", "custom_tool.created", "custom_tool.updated", "custom_tool.deleted", "macro.applied", "cost.budget_alert", "runtime.budget_exceeded", "lead.created", "lead.stage_changed", "lead.pipeline_changed", "lead.assigned", "lead.won", "lead.lost", "lead.unqualified", "order.created", "order.status_changed", "stock.synced", "stock.source_retired", "vehicle.published", "vehicle.unpublished", "vehicle.publish_failed", "vehicle.created", "vehicle.attachment.created", "mercadolibre.order", "mercadolibre.vis_lead", "chileautos.lead", "yapo.lead", "website.lead", "demo_lead.created", "demo_lead.pending_scheduling", "demo_lead.routed", "demo_booking.booked", "demo_booking.rescheduled", "demo_booking.cancelled", "demo_booking.held", "demo_booking.no_show", "consignment.candidate.created", "quote.issued", "quote.voided", "quote.extended", "quote.archived", "reservation.created", "reservation.voided", "reservation.abono_disposed", "reservation.converted", "sale_note.issued", "sale_note.approved", "sale_note.voided", "purchase_note.issued", "purchase_note.corrected", "purchase_note.voided", "payment.recorded", "consignment.created", "consignment.returned", "consignment.sold", "credit_application.recorded", "credit_application.submitted", "credit_application.decided", "credit_application.withdrawn", "price_approval.requested", "price_approval.decided", "contact.created", "contact.updated", "contact.merged", "appointment.booked", "appointment.rescheduled", "appointment.cancelled", "appointment.completed", "appointment.no_show", "appointment.reminded", "appointment.imported", "campaign.sent", "campaign.paused", "sending_domain.verified", "coach.proposals_ready", "coach.finding_ready", "voice.autonomous_call", "safety_hold.placed", "safety_hold.ack_overdue", "safety_hold.first_response_overdue", "team.created", "team.updated", "team.deleted", "custom_role.created", "custom_role.updated", "custom_role.deleted", "macro.created", "macro.updated", "macro.deleted", "assignment_rule.created", "assignment_rule.updated", "assignment_rule.deleted", "sla_policy.created", "sla_policy.updated", "sla_policy.deleted", "automation_trigger.created", "automation_trigger.updated", "automation_trigger.deleted", "sending_domain.created", "sending_domain.deleted", "whatsapp_template.created", "whatsapp_template.status_changed", "whatsapp_template.deleted", "whatsapp_flow.created", "whatsapp_flow.published", "whatsapp_flow.deprecated", "whatsapp_flow.deleted", "whatsapp_flow.completed", "channel.connected", "channel.updated", "channel.disconnected", "membership.created", "membership.updated", "membership.removed", "clinic_professional.created", "clinic_professional.updated", "clinic_professional.deleted", "clinic_service.created", "clinic_service.updated", "clinic_service.deleted", "clinic_price_list.updated", "clinic_pack_purchase.created", "clinic_pack_purchase.session_consumed", "clinic_pack_purchase.cancelled", "clinic_budget.created", "clinic_budget.sent", "clinic_budget.accepted", "clinic_budget.rejected", "clinic_budget.voided", "clinic_budget.mirror_changed", "clinic_cash_session.opened", "clinic_cash_session.closed", "clinic_patient.created", "clinic_patient.updated", "clinic_patient.deleted", "clinic_patient.merged", "clinic_encounter.opened", "clinic_encounter.closed", "clinic_note.signed", "clinic_note.amended", "clinic_consent.signed", "clinic_consent.revoked", "clinic_document.uploaded", "clinic_document.deleted", "clinic_privacy_request.completed" ] }, "minItems": 1, "maxItems": 20 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "include_data": { "type": "boolean", "description": "«Incluir datos del recurso». `false` (the default) = every delivery is the notice: resource, changes, author, time and `url`, with `data_omitted: \"not_requested\"`. `true` = each delivery also carries `data` when, at dispatch time, this subscription's OWNER — whoever created it or last changed its url, events or this flag — holds the resource read scope (`read_scope` in the catalogue) and sees every record; otherwise `data_omitted` says why. An event about a dato sensible is always the notice." } }, "required": [ "url", "events" ], "example": { "url": "https://crm.example.cl/vitrina", "events": [ "lead.created", "lead.stage_changed" ], "description": "CRM sync", "include_data": false } }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "integer", "description": "Pass to `POST …/deliveries/{deliveryId}/redeliver`." }, "subscription_id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "event_id": { "type": "string", "format": "uuid", "description": "The event id — identical across every attempt and redelivery of one event." }, "attempt": { "type": "integer" }, "status_code": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ], "description": "`http_`, `timeout`, or the network error; `null` on success." }, "response_excerpt": { "type": [ "string", "null" ] }, "request_payload": { "type": "object", "additionalProperties": {}, "description": "The exact body that was POSTed." }, "latency_ms": { "type": [ "integer", "null" ] }, "redelivery_of": { "type": [ "integer", "null" ], "description": "Set on a manual redelivery: the delivery row it repeated." }, "created_at": { "type": "string" } }, "required": [ "id", "subscription_id", "event", "event_id", "attempt", "status_code", "error", "response_excerpt", "request_payload", "latency_ms", "redelivery_of", "created_at" ] }, "WebhookRedeliverResult": { "type": "object", "properties": { "subscription_id": { "type": "string", "format": "uuid" }, "delivery_id": { "type": "integer" }, "event": { "type": "string" }, "event_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] } }, "required": [ "subscription_id", "delivery_id", "event", "event_id", "status" ] }, "LeadActivity": { "type": "object", "properties": { "id": { "type": "integer" }, "lead_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "description": "`created`, `stage_changed`, `assigned`, `value_updated`, `won`, `lost`, …" }, "data": { "type": "object", "additionalProperties": {} }, "actor_user_id": { "type": [ "string", "null" ], "description": "The member who acted, when a member did. Prefer `author`." }, "conversation_id": { "type": [ "string", "null" ] }, "author": { "$ref": "#/components/schemas/Author" }, "created_at": { "type": "string" } }, "required": [ "id", "lead_id", "kind", "data", "actor_user_id", "conversation_id", "author", "created_at" ] }, "ContactTagRef": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "display_name": { "type": "string" } }, "required": [ "id", "name", "display_name" ] }, "ContactSearchRow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "display_name": { "type": "string" }, "named": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "string" } }, "lead_sources": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/ContactTagRef" } } }, "required": [ "id", "name", "display_name", "named", "channels", "lead_sources", "tags" ], "additionalProperties": {} }, "AddPaymentMethodResult": { "type": "object", "properties": { "method_id": { "type": "string", "format": "uuid" }, "rail": { "type": "string", "enum": [ "fintoc_pac", "fintoc_card", "oneclick", "mercadopago" ], "description": "The rail that holds the method: `fintoc_pac` (automatic debit from a current account through Fintoc), `fintoc_card` (credit or debit card on file at Fintoc), `oneclick` (card on file at Transbank Webpay Oneclick), `mercadopago` (card on file at Mercado Pago)." }, "status": { "type": "string", "enum": [ "activo", "pendiente" ] }, "redirect": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "enum": [ "GET", "POST" ] }, "fields": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } }, "required": [ "url", "method", "fields" ], "description": "Where to send the browser now: a GET to the PAC checkout, or a form POST of `fields` (TBK_TOKEN) to Transbank. Null when the method is already active." } }, "required": [ "method_id", "rail", "status", "redirect" ] }, "AddPaymentMethodBody": { "type": "object", "properties": { "rail": { "type": "string", "enum": [ "fintoc_pac", "fintoc_card", "oneclick", "mercadopago" ], "description": "The rail that holds the method: `fintoc_pac` (automatic debit from a current account through Fintoc), `fintoc_card` (credit or debit card on file at Fintoc), `oneclick` (card on file at Transbank Webpay Oneclick), `mercadopago` (card on file at Mercado Pago)." }, "return_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "Where the provider sends the browser back — must be on the app’s own origin (the Facturación page). Required for `fintoc_pac`, `fintoc_card` and `oneclick`." }, "cancel_url": { "type": "string", "maxLength": 2048, "format": "uri", "description": "`fintoc_pac` / `fintoc_card`: where a cancelled enrolment lands (defaults to `return_url`)." }, "bank": { "type": "string", "minLength": 1, "maxLength": 64, "description": "`fintoc_pac`: a bank `code` from `pac_banks`; the enrolment opens on it." }, "email": { "type": "string", "maxLength": 320, "format": "email", "description": "The payer email. Defaults to the workspace’s billing email." }, "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "rut": { "type": "string", "minLength": 1, "maxLength": 32 }, "card": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 256 }, "brand": { "type": "string", "minLength": 1, "maxLength": 32 }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" }, "exp_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "exp_year": { "type": "integer", "minimum": 2000, "maximum": 2100 } }, "required": [ "token" ], "description": "`mercadopago`: the card token minted by Mercado Pago’s own SDK, with the brand, last 4 and expiry it reports (display only). Never a card number." }, "pay_invoice_id": { "type": "string", "format": "uuid", "description": "`mercadopago`: «Pagar ahora» — an unpaid cobro of this workspace to collect from the new card right away. The card’s subscription then starts its cycle within about an hour (12:00 Santiago at the earliest) and is armed with that cobro, instead of waiting for the cobro’s scheduled day." } }, "required": [ "rail" ] }, "TransferClaimResult": { "type": "object", "properties": { "created": { "type": "boolean", "description": "False when a claim was already pending (idempotent)." }, "claimedAt": { "type": "string" }, "number": { "type": "string" }, "comprobante": { "allOf": [ { "$ref": "#/components/schemas/ClaimComprobante" }, { "description": "#7094: the comprobante attached by THIS call (null when the call sent none, or it was not stored)." } ] }, "comprobante_error": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "enum": [ "comprobante_not_stored", "no_pending_claim" ] }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "reason", "message", "retryable" ], "description": "#7094: set only when a file was sent and NOT stored. The claim was still made (and is being verified): offer «reintentar adjuntar» through `POST …/transfer-claim/comprobante` when `retryable`, never a second claim." } }, "required": [ "created", "claimedAt", "number", "comprobante", "comprobante_error" ] }, "OverheadPeriod": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-01" }, "GatewayPaymentRef": { "type": [ "object", "null" ], "properties": { "provider": { "type": "string", "enum": [ "mercadopago", "webpay", "fintoc", "flow", "khipu", "bancame" ] }, "payment_id": { "type": "string", "description": "The provider’s own payment id (Mercado Pago payment id; Webpay transaction token; Flow token; Khipu payment id; banca.me externalTrxId, which is the checkout id)." }, "url": { "type": "string", "format": "uri", "description": "Where to look the payment up: the clinic’s Mercado Pago activity search, or the provider’s site for Webpay, Flow, Khipu and banca.me (no per-payment page)." }, "status": { "type": "string", "enum": [ "approved", "partially_refunded", "replaced", "refunded", "charged_back", "reversed" ], "description": "`approved` = the money is in; `partially_refunded` = part went back (`amount_clp` is the net, `refunded_clp` what was refunded); `replaced` = superseded by the net row after a partial refund; `refunded` = returned from Mercado Pago; `charged_back` = the payer’s bank took it back; `reversed` = reversed in Vitrina for another reason. Only `approved` / `partially_refunded` are counted." }, "refunded_clp": { "type": [ "integer", "null" ], "description": "What Mercado Pago refunded of this payment, when known." } }, "required": [ "provider", "payment_id", "url", "status", "refunded_clp" ], "description": "A Mercado Pago checkout payment: its payment id, a link to it and its status. Null for every other movement." }, "ClinicContactPayment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The movement row’s own id — a mirrored pago, a mirrored devolución or a native ledger payment (`kind` + `origin` say which)." }, "kind": { "type": "string", "enum": [ "payment", "refund" ] }, "origin": { "type": "string", "enum": [ "dentalink", "medilink", "reservo", "vitrina" ] }, "paid_on": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "amount_clp": { "type": "integer", "description": "Always positive; `kind` gives the sign." }, "method": { "type": [ "string", "null" ], "description": "The medio's display label: the vendor's (the clinic's /medios catalog, or Reservo's fixed labels) on mirrored rows, the ledger instrument's («Mercado Pago», «Transferencia») on native rows." }, "instrument": { "type": [ "string", "null" ], "description": "Native ledger instrument code (efectivo, transferencia, tarjeta_*, bono, …); null on mirrored rows." }, "folio": { "type": [ "string", "null" ] }, "voided": { "type": "boolean", "description": "Anulado / reversed: shown, never counted in `summary`." }, "patient_id": { "type": [ "string", "null" ], "format": "uuid" }, "patient_name": { "type": [ "string", "null" ], "description": "Filled only when the contact speaks for several patients." }, "concept": { "type": [ "string", "null" ] }, "professional": { "type": [ "string", "null" ] }, "appointment_starts_at": { "type": [ "string", "null" ] }, "boleta": { "type": "string", "enum": [ "available", "unknown", "none" ], "description": "Its boleta: `available` = `GET …/payments/{paymentId}/boleta` serves the PDF; `unknown` = never asked the practice system yet (Dentalink / Medilink) — the same call asks and remembers; `none` = there is no boleta (refunds always)." }, "gateway": { "$ref": "#/components/schemas/GatewayPaymentRef" } }, "required": [ "id", "kind", "origin", "paid_on", "amount_clp", "method", "instrument", "folio", "voided", "patient_id", "patient_name", "concept", "professional", "appointment_starts_at", "boleta", "gateway" ] }, "ClinicContactPaymentsView": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "source": { "type": "object", "properties": { "vendor": { "type": [ "string", "null" ], "enum": [ "dentalink", "medilink", "reservo" ], "description": "Practice system that authors (some of) this clinic's money; null = native Vitrina Clínica." }, "mirrored": { "type": "boolean" }, "mirror_enabled": { "type": "boolean" }, "mirror_from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "vendor", "mirrored", "mirror_enabled", "mirror_from", "last_synced_at" ] }, "mirror_missing": { "type": "boolean", "description": "A connected vendor clinic whose money is NOT mirrored: the history is only what Vitrina recorded natively." }, "patients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "relationship": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "relationship" ] } }, "summary": { "type": "object", "properties": { "total_paid_clp": { "type": "integer" }, "payment_count": { "type": "integer" }, "last_paid_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "outstanding_clp": { "type": [ "integer", "null" ] } }, "required": [ "total_paid_clp", "payment_count", "last_paid_on", "outstanding_clp" ] }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/ClinicContactPayment" } }, "has_more": { "type": "boolean" } }, "required": [ "contact_id", "source", "mirror_missing", "patients", "summary", "payments", "has_more" ] }, "ClinicDiagnostico": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_started", "active", "closed" ] }, "viewer": { "type": "object", "properties": { "may_start": { "type": "boolean" } }, "required": [ "may_start" ] }, "eligibility": { "type": "object", "properties": { "can_start": { "type": "boolean" }, "reason": { "type": [ "string", "null" ], "enum": [ "no_account", "not_dentalink", "money_adopted", "dpa_required", "plan_active", "already_used", "active" ] }, "message": { "type": [ "string", "null" ] }, "available_on": { "type": [ "string", "null" ] } }, "required": [ "can_start", "reason", "message", "available_on" ] }, "window": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "closed" ] }, "phase": { "type": "string", "enum": [ "running", "closing", "closed" ] }, "closing_reason": { "type": [ "string", "null" ], "enum": [ "plan_pending", "finishing" ] }, "held_until": { "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "ends_at": { "type": "string" }, "day": { "type": "integer" }, "days_total": { "type": "integer" }, "days_left": { "type": "integer" }, "warned_at": { "type": [ "string", "null" ] }, "ended_early_at": { "type": [ "string", "null" ] }, "closed_at": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "purged", "kept_plan", "kept_preexisting" ] }, "mirror_origin": { "type": "string", "enum": [ "diagnostico", "preexisting" ] }, "closing": { "type": "object", "properties": { "deletes_detail": { "type": "boolean" }, "sentence": { "type": "string" } }, "required": [ "deletes_detail", "sentence" ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "purged", "residual_purged", "kept_plan", "kept_preexisting", "deferred_plan_pending", "failed" ] }, "finished_at": { "type": "string" }, "deleted": { "type": "object", "properties": { "plans": { "type": "integer" }, "plan_lines": { "type": "integer" }, "payments": { "type": "integer" }, "tax_documents": { "type": "integer" } }, "required": [ "plans", "plan_lines", "payments", "tax_documents" ] } }, "required": [ "outcome", "finished_at", "deleted" ] } } }, "required": [ "id", "status", "phase", "closing_reason", "held_until", "started_at", "ends_at", "day", "days_total", "days_left", "warned_at", "ended_early_at", "closed_at", "outcome", "mirror_origin", "closing", "runs" ] }, "sync": { "type": [ "object", "null" ], "properties": { "state": { "type": "string", "enum": [ "copying", "up_to_date", "error", "off" ] }, "synced_at": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] } }, "required": [ "state", "synced_at", "message" ] }, "report": { "type": [ "object", "null" ], "properties": { "version": { "type": "number", "enum": [ 1 ] }, "computed_at": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "data_through": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "ready", "settling", "empty" ] }, "state_reason": { "type": [ "string", "null" ] }, "collected": { "type": "object", "properties": { "clp": { "type": [ "integer", "null" ] }, "previous_clp": { "type": [ "integer", "null" ] }, "delta_pct": { "type": [ "number", "null" ] }, "rule": { "type": "string" } }, "required": [ "clp", "previous_clp", "delta_pct", "rule" ] }, "acceptance": { "type": "object", "properties": { "presented": { "type": [ "integer", "null" ] }, "accepted": { "type": [ "integer", "null" ] }, "rate": { "type": [ "number", "null" ] }, "presented_clp": { "type": [ "integer", "null" ] }, "accepted_clp": { "type": [ "integer", "null" ] }, "formula_status": { "type": "string", "enum": [ "acordada", "propuesta" ] }, "rule": { "type": "string" } }, "required": [ "presented", "accepted", "rate", "presented_clp", "accepted_clp", "formula_status", "rule" ] }, "cierres": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "value_clp": { "type": [ "integer", "null" ] }, "formula_status": { "type": "string", "enum": [ "acordada", "propuesta" ] }, "rule": { "type": "string" } }, "required": [ "count", "value_clp", "formula_status", "rule" ] }, "by_professional": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": "string" }, "professional_name": { "type": "string" }, "presented": { "type": [ "integer", "null" ] }, "accepted": { "type": [ "integer", "null" ] }, "rate": { "type": [ "number", "null" ] }, "accepted_clp": { "type": [ "integer", "null" ] }, "cierres": { "type": [ "integer", "null" ] }, "cierres_clp": { "type": [ "integer", "null" ] }, "suppressed": { "type": "boolean" } }, "required": [ "professional_id", "professional_name", "presented", "accepted", "rate", "accepted_clp", "cierres", "cierres_clp", "suppressed" ] } }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "accepted_clp": { "type": [ "integer", "null" ] }, "produced_clp": { "type": [ "integer", "null" ] }, "collected_clp": { "type": [ "integer", "null" ] }, "cierres": { "type": [ "integer", "null" ] } }, "required": [ "month", "accepted_clp", "produced_clp", "collected_clp", "cierres" ] } }, "first_visit": { "type": "object", "properties": { "patients": { "type": [ "integer", "null" ] }, "paid": { "type": [ "integer", "null" ] }, "rate": { "type": [ "number", "null" ] }, "formula_status": { "type": "string", "enum": [ "acordada", "propuesta" ] }, "rule": { "type": "string" } }, "required": [ "patients", "paid", "rate", "formula_status", "rule" ] }, "second_visit": { "type": "object", "properties": { "eligible": { "type": [ "integer", "null" ] }, "converted": { "type": [ "integer", "null" ] }, "rate": { "type": [ "number", "null" ] }, "formula_status": { "type": "string", "enum": [ "acordada", "propuesta" ] }, "rule": { "type": "string" } }, "required": [ "eligible", "converted", "rate", "formula_status", "rule" ] }, "botados": { "type": "object", "properties": { "unaccepted": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "clp": { "type": [ "integer", "null" ] }, "suppressed": { "type": "boolean" } }, "required": [ "count", "clp", "suppressed" ] }, "accepted_unscheduled": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "clp": { "type": [ "integer", "null" ] }, "suppressed": { "type": "boolean" } }, "required": [ "count", "clp", "suppressed" ] }, "mid_treatment_no_future_cita": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "clp": { "type": [ "integer", "null" ] }, "suppressed": { "type": "boolean" } }, "required": [ "count", "clp", "suppressed" ] }, "total": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ] }, "clp": { "type": [ "integer", "null" ] }, "suppressed": { "type": "boolean" } }, "required": [ "count", "clp", "suppressed" ] }, "focus": { "type": [ "string", "null" ] }, "formula_status": { "type": "string", "enum": [ "acordada", "propuesta" ] }, "rule": { "type": "string" } }, "required": [ "unaccepted", "accepted_unscheduled", "mid_treatment_no_future_cita", "total", "focus", "formula_status", "rule" ] }, "band": { "type": [ "object", "null" ], "properties": { "band": { "type": "string" }, "count": { "type": "number" }, "has_history": { "type": "boolean" }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "month", "count" ] } }, "uf_month": { "type": [ "number", "null" ] }, "estimated_clp_month": { "type": [ "integer", "null" ] }, "price_label": { "type": [ "string", "null" ] }, "rule": { "type": "string" } }, "required": [ "band", "count", "has_history", "months", "uf_month", "estimated_clp_month", "price_label", "rule" ] } }, "required": [ "version", "computed_at", "from", "to", "data_through", "state", "state_reason", "collected", "acceptance", "cierres", "by_professional", "months", "first_visit", "second_visit", "botados", "band" ] }, "report_source": { "type": [ "string", "null" ], "enum": [ "live", "stored" ] }, "plan": { "type": "object", "properties": { "holds_plan": { "type": "boolean" }, "status": { "type": "string", "enum": [ "none", "awaiting_payment", "active", "past_due" ] } }, "required": [ "holds_plan", "status" ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "started_at": { "type": "string" }, "closed_at": { "type": [ "string", "null" ] }, "outcome": { "type": [ "string", "null" ], "enum": [ "purged", "kept_plan", "kept_preexisting" ] }, "label": { "type": "string" } }, "required": [ "id", "started_at", "closed_at", "outcome", "label" ] } }, "suppression": { "type": [ "object", "null" ], "properties": { "min_count": { "type": "integer" } }, "required": [ "min_count" ] } }, "required": [ "status", "viewer", "eligibility", "window", "sync", "report", "report_source", "plan", "history", "suppression" ] }, "ClinicLinea": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" }, "is_default": { "type": "boolean" }, "archived": { "type": "boolean" }, "leads": { "type": "integer" }, "open_leads": { "type": "integer" }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "match": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "owner" ] } }, "required": [ "id", "match", "source" ] } }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "keyword": { "type": "string" }, "source": { "type": "string", "enum": [ "seed", "owner" ] } }, "required": [ "id", "keyword", "source" ] }, "description": "Words that send a lead without an ad to this Línea. Seeded for dental clinics, edited by the owner." }, "specialties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" } }, "required": [ "id", "nombre" ] } } }, "required": [ "id", "nombre", "is_default", "archived", "leads", "open_leads", "rules", "keywords", "specialties" ] }, "ClinicLineasOverview": { "type": "object", "properties": { "lineas": { "type": "array", "items": { "$ref": "#/components/schemas/ClinicLinea" } }, "unmapped_specialties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": "string" } }, "required": [ "id", "nombre" ] }, "description": "Roster specialties no Línea holds yet, for the owner to place." }, "ads": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string" }, "campaign_name": { "type": [ "string", "null" ] }, "ad_set_name": { "type": [ "string", "null" ] }, "ad_name": { "type": [ "string", "null" ] }, "linea_id": { "type": [ "string", "null" ], "format": "uuid", "description": "`null` = unmapped, listed for the owner to place." }, "via": { "type": [ "string", "null" ], "enum": [ "rule", "specialty_map", "specialty_name" ] }, "matched": { "type": [ "string", "null" ] }, "conversations": { "type": "integer" }, "leads": { "type": "integer" } }, "required": [ "external_id", "campaign_name", "ad_set_name", "ad_name", "linea_id", "via", "matched", "conversations", "leads" ] }, "description": "Every ad that opened a conversation, with its Línea." } }, "required": [ "lineas", "unmapped_specialties", "ads" ] }, "PaymentRegistration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "open", "ambiguous", "matched", "dismissed", "cancelled" ] }, "vendor": { "type": "string", "enum": [ "dentalink", "medilink", "reservo" ] }, "vendor_label": { "type": "string" }, "provider": { "type": "string", "enum": [ "mercadopago" ] }, "provider_reference": { "type": "string", "description": "The Mercado Pago payment number." }, "provider_payment_url": { "type": "string" }, "customer_payment_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "amount_clp": { "type": "integer" }, "paid_on": { "type": "string" }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut" ] }, "concept": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string" }, "label": { "type": "string" }, "appointment_starts_at": { "type": [ "string", "null" ] } }, "required": [ "kind", "label", "appointment_starts_at" ] }, "medio": { "type": "object", "properties": { "code": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "code", "label" ] }, "matched": { "type": [ "object", "null" ], "properties": { "mirror_payment_id": { "type": "string", "format": "uuid" }, "vendor_reference": { "type": "string", "description": "The practice system's own pago number." }, "received_on": { "type": [ "string", "null" ] }, "amount_clp": { "type": "integer" }, "medio": { "type": [ "string", "null" ] }, "voided": { "type": "boolean" }, "by": { "type": "string", "enum": [ "auto_unique", "auto_medio", "auto_reference", "staff" ] }, "at": { "type": "string" } }, "required": [ "mirror_payment_id", "vendor_reference", "received_on", "amount_clp", "medio", "voided", "by", "at" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "mirror_payment_id": { "type": "string", "format": "uuid" }, "vendor_reference": { "type": "string", "description": "The practice system's own pago number." }, "received_on": { "type": [ "string", "null" ] }, "amount_clp": { "type": "integer" }, "medio": { "type": [ "string", "null" ] }, "voided": { "type": "boolean" } }, "required": [ "mirror_payment_id", "vendor_reference", "received_on", "amount_clp", "medio", "voided" ] } }, "dismissed_reason": { "type": [ "string", "null" ], "enum": [ "registered_elsewhere", "not_needed" ] }, "overdue": { "type": "boolean" }, "reminded_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "status", "vendor", "vendor_label", "provider", "provider_reference", "provider_payment_url", "customer_payment_id", "contact_id", "amount_clp", "paid_on", "patient", "concept", "medio", "matched", "candidates", "dismissed_reason", "overdue", "reminded_at", "created_at" ] }, "PaymentRegistrationSettings": { "type": "object", "properties": { "vendor": { "type": [ "string", "null" ], "enum": [ "dentalink", "medilink", "reservo" ] }, "vendor_label": { "type": [ "string", "null" ] }, "mercadopago_medio": { "type": [ "string", "null" ] }, "suggested_medio": { "type": [ "string", "null" ] }, "medios": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "code", "label", "active" ] } }, "reminder_business_days": { "type": "integer" } }, "required": [ "vendor", "vendor_label", "mercadopago_medio", "suggested_medio", "medios", "reminder_business_days" ] }, "BankFeedSources": { "type": "object", "properties": { "email": { "type": "object", "properties": { "available": { "type": "boolean", "enum": [ true ] }, "billed": { "type": "boolean", "enum": [ false ] } }, "required": [ "available", "billed" ] }, "fintoc": { "type": "object", "properties": { "configured": { "type": "boolean" }, "entitled": { "type": "boolean" }, "feature": { "type": "string", "enum": [ "bank_feed_fintoc" ] }, "price_clp_per_bank_month": { "type": [ "number", "null" ] }, "connected_banks": { "type": "number" } }, "required": [ "configured", "entitled", "feature", "price_clp_per_bank_month", "connected_banks" ] }, "bci_api_market": { "type": "object", "properties": { "configured": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string" } }, "required": [ "configured", "reason" ] } }, "required": [ "email", "fintoc", "bci_api_market" ] }, "FintocAccountMatch": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Fintoc's account id." }, "bank_account_id": { "type": "string", "description": "The Finanzas bank account that now stands for it." }, "outcome": { "type": "string", "enum": [ "kept", "adopted", "created" ], "description": "`kept`: this link already had it. `adopted`: the existing account with the same number and currency (created by the Chipax import or a cartola upload) took the link, with its movements. `created`: a new account." }, "reason": { "type": [ "string", "null" ], "enum": [ "several_candidates", "different_bank", "different_holder", "already_fed" ], "description": "Why an account with the same number and currency was NOT adopted (a new one was created instead); null when nothing was in doubt." }, "candidate_bank_account_ids": { "type": "array", "items": { "type": "string" }, "description": "The existing accounts with the same number and currency." } }, "required": [ "account_id", "bank_account_id", "outcome", "reason", "candidate_bank_account_ids" ] }, "BankFeedConnection": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "fintoc", "bci_api_market" ] }, "institution_name": { "type": [ "string", "null" ] }, "holder_name": { "type": [ "string", "null" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number_masked": { "type": [ "string", "null" ] } }, "required": [ "id", "number_masked" ] } }, "enabled": { "type": "boolean" }, "connected_at": { "type": "string" }, "disconnected_at": { "type": [ "string", "null" ] }, "last_sync_at": { "type": [ "string", "null" ] }, "last_sync_status": { "type": [ "string", "null" ] }, "last_sync_error": { "type": [ "string", "null" ] }, "sync_cursor": { "type": [ "string", "null" ] }, "account_matches": { "type": "array", "items": { "$ref": "#/components/schemas/FintocAccountMatch" }, "description": "Connect answer only: what the link did with each of its accounts." } }, "required": [ "id", "provider", "institution_name", "holder_name", "accounts", "enabled", "connected_at", "disconnected_at", "last_sync_at", "last_sync_status", "last_sync_error", "sync_cursor" ] }, "BankFeedFintocConnectBody": { "type": "object", "properties": { "exchange_token": { "type": "string", "minLength": 1, "maxLength": 512 }, "link_token": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "BankFeedIngestResult": { "type": "object", "properties": { "drafts": { "type": "number" }, "inserted": { "type": "number" }, "deduped": { "type": "number" }, "cross_source_twins": { "type": "number" } }, "required": [ "drafts", "inserted", "deduped", "cross_source_twins" ] }, "BankFeedEmailPullBody": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "from", "to" ] }, "FinanzasAccountKind": { "type": "string", "enum": [ "ingreso", "costo", "gasto", "no_operacional" ] }, "FinanzasAccountBehavior": { "type": [ "string", "null" ], "enum": [ "fijo", "variable" ] }, "FinanzasAccountUsage": { "type": "object", "properties": { "month": { "type": "string", "example": "2026-10" }, "total_clp": { "type": "integer", "description": "Whole CLP, NET, signed as the Resultado counts the account in that month (parents roll up their children). A costo / gasto line with no legal document sits in the Resultado’s «Egresos sin documento», not here." }, "count": { "type": "integer", "minimum": 0, "description": "Distinct documents and movements behind `total_clp` (the Resultado drill-down of this account)." }, "last_used_month": { "type": [ "string", "null" ], "description": "Latest `YYYY-MM` with any line on this account or a descendant, up to `month`." }, "used_6m": { "type": "boolean", "description": "Any line in the 6 months ending at `month`, inclusive." } }, "required": [ "month", "total_clp", "count", "last_used_month", "used_6m" ], "description": "Present only when the list was asked with `usage_month`." }, "FinanzasAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "kind": { "$ref": "#/components/schemas/FinanzasAccountKind" }, "behavior": { "$ref": "#/components/schemas/FinanzasAccountBehavior" }, "no_document": { "type": "boolean", "description": "«No lleva documento»: money out classified here never has a legal document. It opens no «Falta documento» case and is not counted in «Egresos sin documento»." }, "position": { "type": "integer" }, "depth": { "type": "integer", "minimum": 1 }, "path": { "type": "string" }, "seeded": { "type": "boolean" }, "has_children": { "type": "boolean" }, "archived_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "usage": { "$ref": "#/components/schemas/FinanzasAccountUsage" } }, "required": [ "id", "parent_id", "name", "description", "kind", "behavior", "no_document", "position", "depth", "path", "seeded", "has_children", "archived_at", "created_at", "updated_at" ] }, "FinanzasAccounts": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasAccount" } } }, "required": [ "accounts" ] }, "FinanzasAccountReview": { "type": "object", "properties": { "month": { "type": "string" }, "in_progress": { "type": "boolean", "description": "The month is the current (proforma) one." }, "classified_pct": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Share of the month’s costo + gasto outflow that has an account, floored to one decimal (99.96 reads 99.9). 100 only when nothing is unclassified. Null when nothing went out." }, "outflow_total_clp": { "type": "integer" }, "unclassified": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer", "description": "Equals the Resultado’s «Egresos sin clasificar» for the month." }, "by_kind": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "purchase", "honorario", "manual_expense", "movement" ] }, "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "kind", "count", "total_clp" ] } }, "with_proposal": { "type": "integer", "description": "How many of them sit in an open, ready `classify` case: Vitrina already proposes an account." } }, "required": [ "count", "total_clp", "by_kind", "with_proposal" ] }, "unclassified_income": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "count", "total_clp" ] }, "findings": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string", "enum": [ "unclassified" ] }, "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "key", "count", "total_clp" ] }, { "type": "object", "properties": { "key": { "type": "string", "enum": [ "duplicate_import" ] }, "count": { "type": "integer" }, "pairs": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "duplicates_id": { "type": "string", "format": "uuid" }, "duplicates_name": { "type": "string" }, "used_6m": { "type": "boolean" } }, "required": [ "account_id", "name", "duplicates_id", "duplicates_name", "used_6m" ] } } }, "required": [ "key", "count", "pairs" ] }, { "type": "object", "properties": { "key": { "type": "string", "enum": [ "unused" ] }, "count": { "type": "integer" }, "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "key", "count", "account_ids" ] } ] } } }, "required": [ "month", "in_progress", "classified_pct", "outflow_total_clp", "unclassified", "unclassified_income", "findings" ] }, "FinanzasAccountReviewDismissBody": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "duplicate_import" ] }, "account_id": { "type": "string", "format": "uuid" } }, "required": [ "key", "account_id" ], "additionalProperties": false }, "FinanzasAccountCreateBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "kind": { "$ref": "#/components/schemas/FinanzasAccountKind" }, "behavior": { "$ref": "#/components/schemas/FinanzasAccountBehavior" }, "no_document": { "type": "boolean" }, "description": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "FinanzasAccountUpdateBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "behavior": { "allOf": [ { "$ref": "#/components/schemas/FinanzasAccountBehavior" }, { "type": "string" } ] }, "no_document": { "type": "boolean" }, "parent_id": { "type": [ "string", "null" ], "format": "uuid" }, "position": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "additionalProperties": false }, "FinanzasConnection": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "bank", "mercado_pago", "sii" ] }, "provider": { "type": "string", "enum": [ "fintoc", "bci_api_market", "mercadopago", "sii" ] }, "institution_name": { "type": [ "string", "null" ] }, "holder_name": { "type": [ "string", "null" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number_masked": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "cuenta_corriente", "cuenta_vista", "cuenta_ahorro", "tarjeta_credito", "linea_credito", "mercado_pago", "otra" ] }, "currency": { "type": "string" } }, "required": [ "id", "number_masked", "type", "currency" ] } }, "movement_count": { "type": "integer" }, "connected_at": { "type": "string" }, "last_sync_at": { "type": [ "string", "null" ] }, "last_successful_sync_at": { "type": [ "string", "null" ] }, "last_sync_error": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ok", "first_sync", "pending", "stale", "error", "login_required", "disconnected" ], "description": "`first_sync`: connected, first read not landed yet (a (re)connect resets it; an empty first read stays `first_sync` for 24 h before it counts as a confirmed empty window). Show «Primera lectura en curso», never «Al día». `pending` is the old name of `first_sync`: never sent any more, kept so existing clients still validate." }, "next_refresh_at": { "type": [ "string", "null" ] }, "first_read_done_at": { "type": [ "string", "null" ], "description": "SII only: the first successful read of documents; null otherwise." }, "backfill_done_at": { "type": [ "string", "null" ], "description": "SII only: every month of the first-sync window was read once; null otherwise." }, "emission_status": { "type": [ "string", "null" ], "enum": [ "certified", "in_certification", "not_needed" ], "description": "SII only: the emission step, apart from reading. `in_certification` while the certificate / mandato step is pending; `not_needed` when no emission was set up; null for banks and Mercado Pago." }, "actions": { "type": "object", "properties": { "sync_now": { "type": "boolean" }, "reconnect": { "type": "boolean" }, "disconnect": { "type": "boolean" } }, "required": [ "sync_now", "reconnect", "disconnect" ] }, "account_matches": { "type": "array", "items": { "$ref": "#/components/schemas/FintocAccountMatch" }, "description": "Connect and reconnect answers only: per linked account, whether it was kept, adopted the existing account with the same number and currency, or created (with the reason a match was not adopted)." } }, "required": [ "id", "kind", "provider", "institution_name", "holder_name", "accounts", "movement_count", "connected_at", "last_sync_at", "last_successful_sync_at", "last_sync_error", "status", "next_refresh_at", "first_read_done_at", "backfill_done_at", "emission_status", "actions" ] }, "FinanzasConnections": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasConnection" } }, "unconnected_sources": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mercado_pago" ] }, "institution_name": { "type": "string" }, "data_until": { "type": "string", "description": "Santiago day (YYYY-MM-DD) of the newest imported movement." }, "movement_count": { "type": "integer" } }, "required": [ "kind", "institution_name", "data_until", "movement_count" ] }, "description": "Sources with imported data but no live connection (ODM Mercado Pago): «Sin conexión · datos hasta el {día}»." }, "fintoc": { "type": "object", "properties": { "configured": { "type": "boolean" }, "entitled": { "type": "boolean" }, "feature": { "type": "string", "enum": [ "bank_feed_fintoc" ] }, "price_clp_per_bank_month": { "type": [ "integer", "null" ] }, "widget_public_key": { "type": [ "string", "null" ] } }, "required": [ "configured", "entitled", "feature", "price_clp_per_bank_month", "widget_public_key" ] }, "stale_after_hours": { "type": "integer" }, "manual_sync_min_interval_minutes": { "type": "integer" } }, "required": [ "connections", "unconnected_sources", "fintoc", "stale_after_hours", "manual_sync_min_interval_minutes" ] }, "FinanzasFintocLinkIntent": { "type": "object", "properties": { "widget_token": { "type": "string" }, "external_id": { "type": "string" } }, "required": [ "widget_token", "external_id" ] }, "FinanzasFintocConnectBody": { "type": "object", "properties": { "exchange_token": { "type": "string", "minLength": 1, "maxLength": 512 }, "link_token": { "type": "string", "minLength": 1, "maxLength": 512 } } }, "FinanzasBankPullLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "institution_name": { "type": [ "string", "null" ] }, "last_sync_at": { "type": [ "string", "null" ] }, "last_successful_sync_at": { "type": [ "string", "null" ] }, "queued": { "type": "boolean" }, "next_refresh_at": { "type": [ "string", "null" ] }, "skipped": { "type": [ "string", "null" ], "enum": [ "login_required", "disconnected" ] } }, "required": [ "id", "institution_name", "last_sync_at", "last_successful_sync_at", "queued", "next_refresh_at", "skipped" ] }, "FinanzasBankPull": { "type": "object", "properties": { "last_sync_at": { "type": [ "string", "null" ] }, "last_successful_sync_at": { "type": [ "string", "null" ] }, "queued": { "type": "boolean" }, "enqueued": { "type": "integer" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasBankPullLink" } }, "min_interval_minutes": { "type": "integer" } }, "required": [ "last_sync_at", "last_successful_sync_at", "queued", "enqueued", "links", "min_interval_minutes" ] }, "FinanzasSyncResult": { "type": "object", "properties": { "enqueued": { "type": "boolean", "enum": [ true ] }, "next_refresh_at": { "type": [ "string", "null" ] } }, "required": [ "enqueued", "next_refresh_at" ] }, "FinanzasHowtoScreen": { "type": "string", "enum": [ "resumen", "por_resolver", "hecho_por_vitrina", "movimientos", "documentos", "contrapartes", "resultado", "flujo_de_caja", "costos_y_equilibrio", "conexiones", "plan_de_cuentas", "reglas" ] }, "FinanzasHowtoVideo": { "type": "object", "properties": { "screen": { "$ref": "#/components/schemas/FinanzasHowtoScreen" }, "url": { "type": "string" }, "embed_url": { "type": "string" } }, "required": [ "screen", "url", "embed_url" ] }, "FinanzasHowtoVideos": { "type": "object", "properties": { "videos": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasHowtoVideo" } } }, "required": [ "videos" ] }, "FinanzasHowtoAdminRow": { "type": "object", "properties": { "screen": { "$ref": "#/components/schemas/FinanzasHowtoScreen" }, "label": { "type": "string" }, "url": { "type": [ "string", "null" ] }, "embed_url": { "type": [ "string", "null" ] } }, "required": [ "screen", "label", "url", "embed_url" ] }, "FinanzasHowtoAdminView": { "type": "object", "properties": { "screens": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasHowtoAdminRow" } }, "allowed_hosts": { "type": "array", "items": { "type": "string" } } }, "required": [ "screens", "allowed_hosts" ] }, "FinanzasHowtoSetBody": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "url" ] }, "FinanzasClaveTributaria": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "activa", "verificando", "requiere_actualizar", "no_configurada" ], "description": "activa | verificando | requiere_actualizar (the SII rejected the stored clave: sync paused until it is updated) | no_configurada." }, "status_changed_at": { "type": [ "string", "null" ] }, "verified_at": { "type": [ "string", "null" ] }, "last_used_at": { "type": [ "string", "null" ] }, "pending_replacement": { "type": [ "object", "null" ], "properties": { "since": { "type": [ "string", "null" ] } }, "required": [ "since" ], "description": "A new clave is being verified; the previous one keeps working until it is." }, "last_verification": { "type": [ "object", "null" ], "properties": { "outcome": { "type": "string", "enum": [ "verified", "rejected", "deferred" ] }, "at": { "type": [ "string", "null" ] } }, "required": [ "outcome", "at" ] }, "consent": { "type": [ "object", "null" ], "properties": { "version": { "type": "string" }, "accepted_at": { "type": "string" }, "current": { "type": "boolean" } }, "required": [ "version", "accepted_at", "current" ] }, "consent_required": { "type": "boolean", "description": "True when the consent screen must be shown before the clave (none on record, or an older text version)." }, "consent_text": { "type": "object", "properties": { "version": { "type": "string" }, "title": { "type": "string" }, "points": { "type": "array", "items": { "type": "string" } }, "authorization": { "type": "string" } }, "required": [ "version", "title", "points", "authorization" ] }, "live": { "type": "boolean", "description": "False when the SII service could not be asked: the last known state." }, "checked_at": { "type": [ "string", "null" ] }, "actions": { "type": "object", "properties": { "connect": { "type": "boolean" }, "update": { "type": "boolean" }, "disconnect": { "type": "boolean" } }, "required": [ "connect", "update", "disconnect" ] } }, "required": [ "connection_id", "status", "status_changed_at", "verified_at", "last_used_at", "pending_replacement", "last_verification", "consent", "consent_required", "consent_text", "live", "checked_at", "actions" ] }, "FinanzasContraparte": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rut": { "type": [ "string", "null" ], "description": "Canonical form `76123456-0`; null = keyed by name." }, "rut_formatted": { "type": [ "string", "null" ], "example": "76.123.456-0" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "supplier", "customer" ] } }, "source": { "type": "string", "enum": [ "movement", "document", "manual", "import" ] }, "contact": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "clinic_patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "is_payroll": { "type": "boolean", "description": "A person on payroll. Without `finanzas_payroll:read` («Ver remuneraciones») the name reads «Persona (remuneraciones)» and the RUT is null." }, "movement_count": { "type": "integer" }, "document_count": { "type": "integer" }, "merged_into_id": { "type": [ "string", "null" ], "description": "Non-null = merged away; use the survivor." }, "payment_terms_days": { "type": [ "integer", "null" ], "description": "Its own payment terms in days (0–365); null = the workspace default of each document class (Ajustes › Plazos de pago)." }, "needs_name": { "type": "boolean", "description": "True while the name is only the RUT (no document has told us the razón social yet): show «Sin nombre aún» + the RUT, never the RUT as a title." }, "payment_terms_source": { "type": [ "string", "null" ], "enum": [ "chipax", "manual" ], "description": "Where `payment_terms_days` came from: chipax (the importer read it) or manual (a person set it); null when it has no terms of its own." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "rut", "rut_formatted", "roles", "source", "contact", "clinic_patient", "is_payroll", "movement_count", "document_count", "merged_into_id", "payment_terms_days", "needs_name", "payment_terms_source", "created_at", "updated_at" ] }, "FinanzasContraparteUpdateBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "clinic_patient_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "FinanzasContraparteMergeResult": { "type": "object", "properties": { "survivor": { "$ref": "#/components/schemas/FinanzasContraparte" }, "merged_id": { "type": "string" }, "merge_id": { "type": "string", "description": "The merge ledger id: `POST /finanzas/contrapartes/merges/{mergeId}/undo` undoes it." }, "moved": { "type": "object", "properties": { "movements": { "type": "integer" }, "documents": { "type": "integer" } }, "required": [ "movements", "documents" ] } }, "required": [ "survivor", "merged_id", "merge_id", "moved" ] }, "FinanzasContraparteMergeBody": { "type": "object", "properties": { "merge_id": { "type": "string", "format": "uuid", "description": "The duplicate that is merged into `{id}`." } }, "required": [ "merge_id" ] }, "FinanzasContraparteDuplicatePair": { "type": "object", "properties": { "keep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut": { "type": [ "string", "null" ] }, "rut_formatted": { "type": [ "string", "null" ] }, "movement_count": { "type": "integer" }, "document_count": { "type": "integer" } }, "required": [ "id", "name", "rut", "rut_formatted", "movement_count", "document_count" ], "description": "The one that stays." }, "merge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut": { "type": [ "string", "null" ] }, "rut_formatted": { "type": [ "string", "null" ] }, "movement_count": { "type": "integer" }, "document_count": { "type": "integer" } }, "required": [ "id", "name", "rut", "rut_formatted", "movement_count", "document_count" ], "description": "The one that is merged into `keep`." }, "score": { "type": "number", "minimum": 0, "maximum": 1 }, "moves": { "type": "object", "properties": { "movements": { "type": "integer" }, "documents": { "type": "integer" } }, "required": [ "movements", "documents" ], "description": "What moves to `keep`." } }, "required": [ "keep", "merge", "score", "moves" ] }, "FinanzasContraparteDuplicates": { "type": "object", "properties": { "total": { "type": "integer", "description": "Every proposed pair; `items` holds the first 200." }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasContraparteDuplicatePair" } } }, "required": [ "total", "items" ] }, "FinanzasContraparteDuplicateMergeBody": { "type": "object", "properties": { "keep_id": { "type": "string", "format": "uuid" }, "merge_id": { "type": "string", "format": "uuid" } }, "required": [ "keep_id", "merge_id" ] }, "FinanzasContraparteDuplicateDismissBody": { "type": "object", "properties": { "a_id": { "type": "string", "format": "uuid" }, "b_id": { "type": "string", "format": "uuid" } }, "required": [ "a_id", "b_id" ] }, "FinanzasContraparteMergeView": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "origin": { "type": "string", "enum": [ "same_rut", "same_name", "review", "manual" ] }, "actor": { "type": "string", "enum": [ "system", "person" ] }, "label": { "type": "string", "example": "Adolfo Cerda A → ADOLFO CERDA ALVAREZ" }, "survivor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "merged": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "moved": { "type": "object", "properties": { "movements": { "type": "integer" }, "documents": { "type": "integer" } }, "required": [ "movements", "documents" ] }, "reason": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "undone_at": { "type": [ "string", "null" ] }, "undoable": { "type": "boolean" } }, "required": [ "id", "origin", "actor", "label", "survivor", "merged", "moved", "reason", "created_at", "undone_at", "undoable" ] }, "FinanzasContraparteUndoMergeResult": { "type": "object", "properties": { "merge_id": { "type": "string", "format": "uuid" }, "survivor": { "$ref": "#/components/schemas/FinanzasContraparte" }, "restored": { "$ref": "#/components/schemas/FinanzasContraparte" }, "moved_back": { "type": "object", "properties": { "movements": { "type": "integer" }, "documents": { "type": "integer" } }, "required": [ "movements", "documents" ] } }, "required": [ "merge_id", "survivor", "restored", "moved_back" ] }, "FinanzasContraparteTerms": { "type": "object", "properties": { "days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365, "description": "Its own terms; null = the workspace default per class." }, "by_class": { "type": "array", "items": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "suppliers", "customers", "honorarios", "expenses" ], "description": "Document class: suppliers = compras (proveedores), customers = ventas (clientes), honorarios = boletas de honorarios, expenses = gastos." }, "label": { "type": "string" }, "days": { "type": "integer" }, "source": { "type": "string", "enum": [ "contraparte", "workspace", "default" ] }, "origin": { "type": "string", "enum": [ "chipax", "default", "manual" ], "description": "Where the number comes from: chipax (read from the Chipax company by the importer), manual (set by a person in Ajustes or on the Contraparte), default (the built-in 30 / 30 / 0 / 0)." } }, "required": [ "class", "label", "days", "source", "origin" ] } } }, "required": [ "days", "by_class" ] }, "FinanzasContraparteAlias": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "rut", "bank_account", "descriptor" ], "description": "`descriptor`: a card / automatic-debit descriptor (a bank line with no RUT or account) learned when a person confirmed such a movement in «Por resolver» against this Contraparte's documents. Removed like any alias (`DELETE …/aliases/{aliasId}`); never added by hand." }, "display": { "type": "string", "description": "A RUT formatted (`16.123.456-7`); an account masked; a descriptor folded (`MERPAGO*MERCADOL`)." }, "created_at": { "type": "string" } }, "required": [ "id", "kind", "display", "created_at" ] }, "FinanzasAccountRef": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "path": { "type": "string" }, "kind": { "type": "string", "enum": [ "ingreso", "costo", "gasto", "no_operacional" ] }, "archived": { "type": "boolean" } }, "required": [ "id", "name", "path", "kind", "archived" ] }, "FinanzasRule": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "label": { "type": "string", "description": "The rule as one Spanish sentence." }, "target": { "type": "string", "enum": [ "document", "movement" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "rut": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut" ] }, "text_contains": { "type": [ "string", "null" ] }, "amount_min_clp": { "type": [ "integer", "null" ] }, "amount_max_clp": { "type": [ "integer", "null" ] }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ] }, "document_kind": { "type": [ "string", "null" ] }, "account": { "$ref": "#/components/schemas/FinanzasAccountRef" }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "origin": { "type": "string", "enum": [ "person", "vitrina" ], "description": "person = created by a person; vitrina = Vitrina created it, after a person confirmed the same classification twice for this Contraparte or from a consistent history (≥3 items, ≥90 % on one account), announced in «Hecho por Vitrina». Archive it to say no: Vitrina never proposes it again." }, "accrual": { "type": "string", "enum": [ "issue_month", "previous_month" ], "description": "The month the rule books a document in: issue_month, or previous_month («mes anterior»)." }, "accrual_set_by": { "type": "string", "enum": [ "default", "vitrina", "person" ], "description": "Who chose `accrual`: default, vitrina (learned from where this supplier's documents were booked before) or person." }, "run_count": { "type": "integer" }, "last_applied_at": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "label", "target", "contraparte", "text_contains", "amount_min_clp", "amount_max_clp", "direction", "document_kind", "account", "status", "origin", "accrual", "accrual_set_by", "run_count", "last_applied_at", "created_at", "updated_at" ] }, "FinanzasContrapartePage": { "type": "object", "properties": { "contraparte": { "$ref": "#/components/schemas/FinanzasContraparte" }, "balance": { "type": "object", "properties": { "payable": { "type": "object", "properties": { "open_clp": { "type": "integer" }, "overdue_clp": { "type": "integer" }, "open_count": { "type": "integer" }, "overdue_count": { "type": "integer" }, "oldest_overdue_due_date": { "type": [ "string", "null" ] }, "next_due_date": { "type": [ "string", "null" ] } }, "required": [ "open_clp", "overdue_clp", "open_count", "overdue_count", "oldest_overdue_due_date", "next_due_date" ], "description": "What the workspace owes it: open purchases, honorarios and gastos." }, "receivable": { "type": "object", "properties": { "open_clp": { "type": "integer" }, "overdue_clp": { "type": "integer" }, "open_count": { "type": "integer" }, "overdue_count": { "type": "integer" }, "oldest_overdue_due_date": { "type": [ "string", "null" ] }, "next_due_date": { "type": [ "string", "null" ] } }, "required": [ "open_clp", "overdue_clp", "open_count", "overdue_count", "oldest_overdue_due_date", "next_due_date" ], "description": "What it owes the workspace: open sales and issued boletas de honorarios (their líquido)." } }, "required": [ "payable", "receivable" ] }, "terms": { "$ref": "#/components/schemas/FinanzasContraparteTerms" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasContraparteAlias" } }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasRule" } }, "open_case": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "description": "Its open «Por resolver» case (the biggest at stake when it has several), to link to `GET /finanzas/cases/{id}`; null when none." }, "as_of": { "type": "string", "description": "Today (America/Santiago)." } }, "required": [ "contraparte", "balance", "terms", "aliases", "rules", "open_case", "as_of" ] }, "FinanzasMovement": { "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "example": "2026-10-29" }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer", "description": "Whole CLP, > 0 (the CLP equivalent for USD)." }, "currency": { "type": "string", "enum": [ "CLP", "USD" ] }, "original": { "type": [ "object", "null" ], "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "amount_minor": { "type": "integer", "description": "Cents." }, "fx_rate_clp": { "type": "number", "description": "CLP per 1 USD." }, "fx_rate_date": { "type": "string" } }, "required": [ "currency", "amount_minor", "fx_rate_clp", "fx_rate_date" ] }, "description": { "type": [ "string", "null" ] }, "counterparty_name": { "type": [ "string", "null" ] }, "counterparty_rut_formatted": { "type": [ "string", "null" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rut_formatted": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut_formatted" ] }, "bank_account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "institution_name": { "type": [ "string", "null" ] }, "number_masked": { "type": [ "string", "null" ] }, "currency": { "type": "string", "enum": [ "CLP", "USD" ] } }, "required": [ "id", "name", "institution_name", "number_masked", "currency" ] }, "state": { "type": "string", "enum": [ "open", "partial", "reconciled" ] }, "assigned_clp": { "type": "integer" }, "pending_clp": { "type": "integer" }, "resolved_by": { "type": [ "string", "null" ], "enum": [ "rule", "match", "ai", "person" ] }, "source": { "type": "string", "enum": [ "bank_feed", "email", "mercado_pago", "cartola" ] }, "operation_id": { "type": [ "string", "null" ] }, "payer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "name", "email" ], "description": "Who paid, as a payment processor reports it (Mercado Pago: name and e-mail). Null for bank movements." }, "comment_count": { "type": "integer" }, "ads_document_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Finanzas 30: the ad document (`GET /finanzas/documents/{id}`, `origin = ads`) of this movement when it is an ad charge or refund; null otherwise." }, "card_processor": { "type": [ "object", "null" ], "properties": { "key": { "type": "string", "enum": [ "pagos_y_servicios", "transbank", "getnet", "mercado_pago", "healthatom" ] }, "name": { "type": "string" }, "rut_formatted": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "rut_formatted" ], "description": "Finanzas 36: set when this is a known card processor's payout («Cobro con tarjeta»: PNOL / PAGOS Y SERVICIOS, Transbank, Getnet, Mercado Pago). It settles the month's boleta summary and never adds income. Null for any other movement and for money out." }, "generic_label": { "type": [ "string", "null" ], "enum": [ "Depósito en efectivo", "Pago recibido", "Depósito con cheque", "Pago de tarjeta de crédito" ], "description": "Finanzas 36: set when the bank text names nobody and the movement has no Contraparte: show it as the title with the sub-line «Sin contraparte»." }, "created_at": { "type": "string" } }, "required": [ "id", "date", "direction", "amount_clp", "currency", "original", "description", "counterparty_name", "counterparty_rut_formatted", "contraparte", "bank_account", "state", "assigned_clp", "pending_clp", "resolved_by", "source", "operation_id", "payer", "comment_count", "ads_document_id", "card_processor", "generic_label", "created_at" ] }, "FinanzasDocument": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "purchase", "sale", "honorario", "manual_expense", "tax" ] }, "source": { "type": "string", "enum": [ "sii", "vitrina", "manual", "chipax" ] }, "dte_type": { "type": [ "integer", "null" ] }, "dte_type_label": { "type": [ "string", "null" ], "example": "Factura electrónica" }, "is_credit_note": { "type": "boolean", "description": "DTE 61: the libro subtracts it." }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string", "example": "2026-10-03" }, "period": { "type": "string", "example": "2026-10" }, "received_on": { "type": [ "string", "null" ] }, "issuer_rut_formatted": { "type": [ "string", "null" ] }, "receiver_rut_formatted": { "type": [ "string", "null" ] }, "counterparty_name": { "type": [ "string", "null" ], "description": "The other side, as the document names it." }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut_formatted": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut_formatted" ] }, "amounts": { "type": "object", "properties": { "net": { "type": "integer" }, "exempt": { "type": "integer" }, "iva": { "type": "integer" }, "other_taxes": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "net", "exempt", "iva", "other_taxes", "total" ], "description": "Whole CLP as the document prints them — positive also on a nota de crédito." }, "due_date": { "type": [ "string", "null" ] }, "payment_state": { "type": "string", "enum": [ "por_pagar", "parcial", "pagado", "vencido_heredado" ], "description": "por_pagar (a sale: por cobrar) | parcial | pagado. Derived from reconciliation; a document settled without a bank link (`settlement`) is pagado. `vencido_heredado` is retired (Finanzas 50): nothing writes it; only rows written before it, outside that backfill, still carry it, and they count like a paid document." }, "settlement": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "enum": [ "person", "paid_before_vitrina" ], "description": "paid_before_vitrina = «Pagado antes de Vitrina»: from a period closed before Vitrina, still open there, so treated as settled (out of the cash projection and the balances). person = someone marked it pagado («Marcar pagada»)." }, "batch_id": { "type": "string", "format": "uuid" }, "settled_at": { "type": "string", "format": "date-time" } }, "required": [ "reason", "batch_id", "settled_at" ], "description": "Settled without a bank link (Finanzas 50); null when the state comes from reconciliation alone. POST /finanzas/documents/{id}/reopen undoes it." }, "sii_estado_contable": { "type": [ "string", "null" ], "description": "REGISTRO | PENDIENTE | NO_INCLUIR | RECLAMADO (purchases)." }, "missing_at_sii": { "type": "boolean", "description": "The SII register no longer lists it; out of the libro." }, "voided": { "type": "boolean" }, "adjusts": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "dte_type": { "type": [ "integer", "null" ] }, "dte_type_label": { "type": [ "string", "null" ] }, "folio": { "type": [ "string", "null" ] } }, "required": [ "id", "dte_type", "dte_type_label", "folio" ], "description": "A nota de crédito / débito: the document it adjusts." }, "f29": { "type": [ "object", "null" ], "properties": { "period": { "type": "string", "example": "2026-09" }, "state": { "type": "string", "enum": [ "proposal", "in_progress", "filed", "rejected" ], "description": "proposal = computed, not filed; in_progress = submitted, the SII has not answered; filed = accepted by the SII; rejected = the latest filing was rejected." }, "state_label": { "type": "string", "example": "Declarado" }, "filed": { "type": "boolean" }, "amount_is_final": { "type": "boolean", "description": "false while the amount is the proposal, not a filed one." }, "filed_at": { "type": [ "string", "null" ] }, "filing_folio": { "type": [ "string", "null" ] }, "rectifications": { "type": "integer", "description": "Accepted filings of the period beyond the first." }, "summary": { "type": [ "object", "null" ], "properties": { "iva_debito": { "type": "integer" }, "iva_credito": { "type": "integer" }, "iva_retenido": { "type": "integer" }, "remanente_anterior": { "type": "integer" }, "remanente_siguiente": { "type": "integer" }, "ppm": { "type": "integer" } }, "required": [ "iva_debito", "iva_credito", "iva_retenido", "remanente_anterior", "remanente_siguiente", "ppm" ] } }, "required": [ "period", "state", "state_label", "filed", "amount_is_final", "filed_at", "filing_folio", "rectifications", "summary" ], "description": "F29 only (`kind = tax`); null on every other kind. The amount to pay is `amounts.total`, the due date `due_date`, paid or not `payment_state`." }, "honorario": { "type": [ "object", "null" ], "properties": { "direction": { "type": "string", "enum": [ "received", "issued" ] }, "gross": { "type": "integer", "description": "«Total honorarios», whole CLP (= amounts.total)." }, "retention": { "type": "integer", "description": "The retención (F29 código 151 when received)." }, "net": { "type": "integer", "description": "Líquido: gross − retención. What is paid, and what reconciliation settles." }, "state": { "type": "string", "enum": [ "vigente", "anulada" ] } }, "required": [ "direction", "gross", "retention", "net", "state" ], "description": "Boletas de honorarios only (kind honorario); null on every other kind." }, "ads": { "type": [ "object", "null" ], "properties": { "platform": { "type": "string", "enum": [ "meta_ads", "google_ads" ] }, "kind": { "type": "string", "enum": [ "charge", "refund" ] }, "movement_id": { "type": [ "string", "null" ], "format": "uuid" }, "verdict": { "type": "string", "enum": [ "new", "pending", "linked", "unconfirmed", "no_connection" ], "description": "linked = Vitrina linked the movement (see evidence); unconfirmed / no_connection = waiting in «Por resolver»; pending = the ad data could not be read yet; new = not decided." }, "reason": { "type": [ "string", "null" ] }, "ad_account_id": { "type": [ "string", "null" ] }, "customer_id": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ], "description": "Meta: the card statement reference (`FACEBK *`)." }, "meta_transaction_id": { "type": [ "string", "null" ], "description": "Meta's «Transaction ID» of the charge, once linked." }, "evidence": { "type": [ "string", "null" ] }, "spend_window": { "type": [ "object", "null" ], "properties": { "ad_account_id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "spend_minor": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "ad_account_id", "from", "to", "spend_minor", "currency" ] }, "currency": { "type": [ "string", "null" ], "description": "The card movement's original currency." }, "amount_original": { "type": [ "number", "null" ] } }, "required": [ "platform", "kind", "movement_id", "verdict", "reason", "ad_account_id", "customer_id", "reference", "meta_transaction_id", "evidence", "spend_window", "currency", "amount_original" ], "description": "Finanzas 30: a document Vitrina made from a Meta / Google card charge (`origin = ads`); null on every other document." }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "kind", "source", "dte_type", "dte_type_label", "is_credit_note", "folio", "issue_date", "period", "received_on", "issuer_rut_formatted", "receiver_rut_formatted", "counterparty_name", "contraparte", "amounts", "due_date", "payment_state", "settlement", "sii_estado_contable", "missing_at_sii", "voided", "adjusts", "f29", "honorario", "created_at", "updated_at" ] }, "FinanzasContraparteTimelineItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "movement" ] }, "date": { "type": "string" }, "movement": { "$ref": "#/components/schemas/FinanzasMovement" }, "document": { "$ref": "#/components/schemas/FinanzasDocument" }, "paid_clp": { "type": "integer" }, "outstanding_clp": { "type": "integer" }, "overdue": { "type": "boolean" } }, "required": [ "type", "date" ] }, "FinanzasContraparteTermsResult": { "type": "object", "properties": { "terms": { "$ref": "#/components/schemas/FinanzasContraparteTerms" }, "recomputed_documents": { "type": "integer" } }, "required": [ "terms", "recomputed_documents" ] }, "FinanzasContraparteTermsBody": { "type": "object", "properties": { "days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365, "description": "Payment terms in days; null = back to the defaults." } }, "required": [ "days" ] }, "FinanzasContraparteAliasChange": { "type": "object", "properties": { "alias": { "allOf": [ { "$ref": "#/components/schemas/FinanzasContraparteAlias" }, { "type": [ "object", "null" ] } ] }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasContraparteAlias" } }, "reconciled": { "type": [ "object", "null" ], "properties": { "documents": { "type": "integer" }, "transfers": { "type": "integer" }, "cash_deposits": { "type": "integer" }, "payments": { "type": "integer" }, "expenses": { "type": "integer" } }, "required": [ "documents", "transfers", "cash_deposits", "payments", "expenses" ], "description": "What the reconciliation engine linked right after (last 60 days)." } }, "required": [ "alias", "aliases", "reconciled" ] }, "FinanzasContraparteAliasBody": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rut", "bank_account" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 60, "description": "A RUT in any punctuation, or a bank account number (digits; dashes and leading zeros are ignored)." } }, "required": [ "kind", "value" ] }, "FinanzasContraparteAliasRemoved": { "type": "object", "properties": { "removed": { "$ref": "#/components/schemas/FinanzasContraparteAlias" }, "aliases": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasContraparteAlias" } } }, "required": [ "removed", "aliases" ] }, "FinanzasPaymentTermsDefault": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "suppliers", "customers", "honorarios", "expenses" ], "description": "Document class: suppliers = compras (proveedores), customers = ventas (clientes), honorarios = boletas de honorarios, expenses = gastos." }, "label": { "type": "string" }, "days": { "type": "integer" }, "customized": { "type": "boolean" }, "source": { "type": "string", "enum": [ "chipax", "default", "manual" ], "description": "Where the number comes from: chipax (read from the Chipax company by the importer), manual (set by a person in Ajustes or on the Contraparte), default (the built-in 30 / 30 / 0 / 0)." }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "class", "label", "days", "customized", "source", "updated_at" ] }, "FinanzasPaymentTermsResult": { "type": "object", "properties": { "defaults": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasPaymentTermsDefault" } }, "recomputed_documents": { "type": "integer" } }, "required": [ "defaults", "recomputed_documents" ] }, "FinanzasPaymentTermsBody": { "type": "object", "properties": { "suppliers": { "type": "integer", "minimum": 0, "maximum": 365 }, "customers": { "type": "integer", "minimum": 0, "maximum": 365 }, "honorarios": { "type": "integer", "minimum": 0, "maximum": 365 }, "expenses": { "type": "integer", "minimum": 0, "maximum": 365 } }, "additionalProperties": false }, "FinanzasCashPendingSummary": { "type": "object", "properties": { "amount_clp": { "type": "integer", "description": "Whole CLP of cash still to deposit (the standing list of the last `window_days` days up to yesterday, minus what deposits already cover)." }, "window_days": { "type": "integer", "description": "The window the amount is read over (60)." }, "expected_until": { "type": [ "string", "null" ], "description": "Last day the Flujo expects the deposits (5 business days from today); null when nothing is pending." } }, "required": [ "amount_clp", "window_days", "expected_until" ] }, "FinanzasMovementComment": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "string" }, "author": { "type": [ "object", "null" ], "properties": { "user_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "user_id", "name" ] }, "created_at": { "type": "string" } }, "required": [ "id", "body", "author", "created_at" ] }, "FinanzasMovementDetail": { "allOf": [ { "$ref": "#/components/schemas/FinanzasMovement" }, { "type": "object", "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasMovementComment" } } }, "required": [ "comments" ] } ] }, "FinanzasMovementCommentBody": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "body" ] }, "FinanzasBankAccount": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "institution_name": { "type": [ "string", "null" ] }, "number_masked": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP", "USD" ] }, "source": { "type": "string", "enum": [ "fintoc", "mercado_pago", "manual" ] }, "has_feed": { "type": "boolean" }, "balance_clp": { "type": [ "integer", "null" ] }, "balance_original": { "type": [ "object", "null" ], "properties": { "currency": { "type": "string", "enum": [ "USD" ] }, "amount_minor": { "type": "integer", "description": "Cents." }, "fx_rate_clp": { "type": "number", "description": "CLP per 1 USD." }, "fx_rate_date": { "type": "string" } }, "required": [ "currency", "amount_minor", "fx_rate_clp", "fx_rate_date" ] }, "balance_as_of": { "type": [ "string", "null" ] }, "balance_source": { "type": "string", "enum": [ "feed", "computed", "unknown" ] }, "opening_balance": { "type": [ "object", "null" ], "properties": { "amount_minor": { "type": "integer" }, "on": { "type": "string" } }, "required": [ "amount_minor", "on" ] }, "opening_balance_editable": { "type": "boolean" }, "movement_count": { "type": "integer" }, "data_through": { "type": [ "string", "null" ], "description": "Date of the account's newest movement (YYYY-MM-DD)." }, "stale": { "type": "boolean", "description": "true = no connection feeds the account and its newest movement is older than 37 days: its cartola is late (warning, never sent as an email or WhatsApp)." }, "agent_sharing": { "type": [ "object", "null" ], "properties": { "shared": { "type": "boolean", "description": "true = the AI agent dictates this account for transfers and abonos into it are matched; false = it stopped sharing it." }, "alias": { "type": "string" }, "holder_name": { "type": "string" }, "holder_rut": { "type": "string" }, "holder_email": { "type": [ "string", "null" ] }, "account_type": { "type": "string", "enum": [ "corriente", "vista", "ahorro" ] }, "holder_not_company": { "type": "boolean", "description": "true = the holder RUT differs from the company RUT (the workspace's SII RUTs): the account card shows «El titular no es la empresa». Always false when the company RUT is not known." } }, "required": [ "shared", "alias", "holder_name", "holder_rut", "holder_email", "account_type", "holder_not_company" ], "description": "Finanzas 33: «el agente comparte esta cuenta», with the holder details the agent dictates. Null = never shared." }, "can_share_with_agent": { "type": "boolean", "description": "Whether the agent can share it: a CLP corriente / vista / ahorro / Mercado Pago account with its full number (not a card, a credit line, a USD account or a last-4 number)." } }, "required": [ "id", "name", "institution_name", "number_masked", "type", "currency", "source", "has_feed", "balance_clp", "balance_original", "balance_as_of", "balance_source", "opening_balance", "opening_balance_editable", "movement_count", "data_through", "stale", "agent_sharing", "can_share_with_agent" ] }, "FinanzasBankAccounts": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasBankAccount" } }, "total_clp": { "type": "integer" }, "as_of": { "type": [ "string", "null" ] }, "unknown_count": { "type": "integer" } }, "required": [ "accounts", "total_clp", "as_of", "unknown_count" ] }, "FinanzasOpeningBalanceBody": { "type": "object", "properties": { "amount_minor": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Balance at the END of `on`, in the account currency smallest unit (CLP pesos, USD cents). null clears it." }, "on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "amount_minor" ] }, "FinanzasAgentSharingBody": { "type": "object", "properties": { "shared": { "type": "boolean", "description": "true = the AI agent shares this account for transfers (and abonos into it are matched); false = stop sharing it (the row is kept, never deleted)." }, "confirm_holder_not_company": { "type": "boolean", "description": "Required (true) to turn sharing on when the holder RUT is not the company's; without it the call answers 409 `agent_sharing_holder_not_company` naming the holder. Never needed to keep an already-shared account or to stop sharing. Set it only after the human has explicitly agreed; an agent must not add it by itself to get past the 409." }, "alias": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The label the agent and Ajustes show. Default «‹banco› ··‹últimos 4›»." }, "holder_name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Account holder as the bank shows it. Required the first time the account is shared." }, "holder_rut": { "type": "string", "minLength": 1, "maxLength": 20, "description": "Holder RUT (any formatting, check digit validated). Default: the workspace's SII RUT." }, "holder_email": { "type": [ "string", "null" ], "maxLength": 254, "format": "email" }, "account_type": { "type": "string", "enum": [ "corriente", "vista", "ahorro" ], "description": "What the agent dictates. Default from the account type (Mercado Pago = vista)." } }, "required": [ "shared" ] }, "FinanzasF29Overview": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasDocument" }, "description": "F29 documents (`kind = tax`), newest period first." }, "next_due": { "type": [ "object", "null" ], "properties": { "period": { "type": "string" }, "due_date": { "type": "string" }, "amount": { "type": [ "integer", "null" ], "description": "Whole CLP; null while the F29 amount is not known yet." }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "type": [ "string", "null" ], "enum": [ "proposal", "in_progress", "filed", "rejected" ] } }, "required": [ "period", "due_date", "amount", "document_id", "state" ] } }, "required": [ "from", "to", "periods", "next_due" ] }, "FinanzasLibro": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "purchase", "sale" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "months": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string" }, "count": { "type": "integer" }, "net": { "type": "integer" }, "exempt": { "type": "integer" }, "iva": { "type": "integer" }, "other_taxes": { "type": "integer" }, "total": { "type": "integer" }, "iva_fiscal": { "type": "integer", "description": "Purchases: IVA crédito fiscal (REGISTRO only). Sales: IVA débito fiscal." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "dte_type": { "type": [ "integer", "null" ] }, "dte_type_label": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "net": { "type": "integer" }, "exempt": { "type": "integer" }, "iva": { "type": "integer" }, "other_taxes": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "dte_type", "dte_type_label", "count", "net", "exempt", "iva", "other_taxes", "total" ] } } }, "required": [ "period", "count", "net", "exempt", "iva", "other_taxes", "total", "iva_fiscal", "lines" ] } }, "totals": { "type": "object", "properties": { "count": { "type": "integer" }, "net": { "type": "integer" }, "exempt": { "type": "integer" }, "iva": { "type": "integer" }, "other_taxes": { "type": "integer" }, "total": { "type": "integer" }, "iva_fiscal": { "type": "integer" } }, "required": [ "count", "net", "exempt", "iva", "other_taxes", "total", "iva_fiscal" ] } }, "required": [ "kind", "from", "to", "months", "totals" ] }, "FinanzasHonorariosSummary": { "type": "object", "properties": { "period": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP" ] }, "received": { "type": "object", "properties": { "count": { "type": "integer" }, "gross_clp": { "type": "integer" }, "retention_clp": { "type": "integer" }, "net_clp": { "type": "integer" } }, "required": [ "count", "gross_clp", "retention_clp", "net_clp" ] }, "issued": { "type": "object", "properties": { "count": { "type": "integer" }, "gross_clp": { "type": "integer" }, "retention_clp": { "type": "integer" }, "net_clp": { "type": "integer" } }, "required": [ "count", "gross_clp", "retention_clp", "net_clp" ] }, "f29_codigo_151_clp": { "type": "integer", "description": "The retención on the boletas the company received in the month (F29 código 151)." }, "clave_status": { "type": "string", "enum": [ "activa", "verificando", "requiere_actualizar", "no_configurada" ], "description": "The SII clave status. Anything but activa: zeros mean «unknown», not «none»." } }, "required": [ "period", "currency", "received", "issued", "f29_codigo_151_clp", "clave_status" ] }, "FinanzasDocumentFile": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_review", "confirmed", "discarded", "failed" ], "description": "pending_review = read, waiting for a person («Por revisar»); confirmed = it is (or is attached to) `document_id`; discarded; failed = not a readable file." }, "channel": { "type": "string", "enum": [ "upload", "email" ] }, "filename": { "type": "string" }, "mime_type": { "type": "string" }, "byte_size": { "type": "integer" }, "url": { "type": [ "string", "null" ], "description": "Short-lived signed URL of the file (private storage); ask again after `url_expires_at`. Null once discarded." }, "url_expires_at": { "type": [ "string", "null" ] }, "movement_id": { "type": [ "string", "null" ], "format": "uuid" }, "case_id": { "type": [ "string", "null" ], "format": "uuid" }, "email": { "type": [ "object", "null" ], "properties": { "from": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] } }, "required": [ "from", "subject" ] }, "extraction_status": { "type": "string", "enum": [ "pending", "complete", "partial", "failed" ] }, "extracted": { "type": "object", "properties": { "total_clp": { "type": [ "integer", "null" ] }, "currency": { "type": [ "string", "null" ] }, "amount_original": { "type": [ "number", "null" ], "description": "The printed amount when the currency is not CLP." }, "fx_rate_clp": { "type": [ "number", "null" ], "description": "The dólar observado a USD amount was converted at." }, "issue_date": { "type": [ "string", "null" ] }, "issuer_rut": { "type": [ "string", "null" ] }, "issuer_name": { "type": [ "string", "null" ] }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "total_clp", "currency", "amount_original", "fx_rate_clp", "issue_date", "issuer_rut", "issuer_name", "dte_type", "folio", "description" ], "description": "What Vitrina read. Every field is editable on confirm." }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "total_clp", "issue_date", "issuer" ] }, "description": "What the reading could not find." }, "error": { "type": [ "string", "null" ] }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string" }, "confirmed_at": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "channel", "filename", "mime_type", "byte_size", "url", "url_expires_at", "movement_id", "case_id", "email", "extraction_status", "extracted", "missing", "error", "document_id", "created_at", "confirmed_at" ] }, "FinanzasDocumentDetail": { "allOf": [ { "$ref": "#/components/schemas/FinanzasDocument" }, { "type": "object", "properties": { "adjusted_by": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dte_type": { "type": [ "integer", "null" ] }, "dte_type_label": { "type": [ "string", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "total": { "type": "integer" } }, "required": [ "id", "dte_type", "dte_type_label", "folio", "issue_date", "total" ] } }, "description": { "type": [ "string", "null" ], "description": "What it was for (manual documents)." }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasDocumentFile" }, "description": "The files behind it (uploads and forwarded emails)." } }, "required": [ "adjusted_by", "description", "files" ] } ] }, "FinanzasDocumentFileConfirmResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "created", "attached" ] }, "document": { "$ref": "#/components/schemas/FinanzasDocumentDetail" }, "file": { "$ref": "#/components/schemas/FinanzasDocumentFile" }, "case_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The «Por resolver» case the document sits in now (open it to confirm the match); null when nothing is left to resolve." }, "edited": { "type": "object", "additionalProperties": { "type": "object", "properties": { "read": {}, "confirmed": {} } } } }, "required": [ "outcome", "document", "file", "case_id", "edited" ] }, "FinanzasDocumentReopenResult": { "type": "object", "properties": { "reopened": { "type": "boolean", "description": "false when nothing settled the document (already open): idempotent." }, "document": { "$ref": "#/components/schemas/FinanzasDocumentDetail" } }, "required": [ "reopened", "document" ] }, "FinanzasInbox": { "type": "object", "properties": { "address": { "type": "string", "example": "finanzas+k7m2q9xw4pha@vitrinadev.com" }, "accepts_from": { "type": "string", "enum": [ "workspace_members" ] }, "created_at": { "type": "string" }, "rotated_at": { "type": [ "string", "null" ] } }, "required": [ "address", "accepts_from", "created_at", "rotated_at" ] }, "FinanzasCartolaFormat": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "bank": { "type": "string" } }, "required": [ "id", "label", "bank" ] }, "FinanzasManualAccountBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "institution_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "description": "The bank or card issuer, e.g. «Banco de Chile»." }, "number": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 40, "description": "Account or card number; only the last digits are shown." }, "type": { "type": "string", "enum": [ "cuenta_corriente", "cuenta_vista", "cuenta_ahorro", "tarjeta_credito", "linea_credito", "otra" ] }, "currency": { "type": "string", "enum": [ "CLP", "USD" ], "description": "Default CLP." } }, "required": [ "name", "type" ] }, "FinanzasCartolaContinuity": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "ok", "gap", "bootstrap", "not_checked" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "no_balance_in_file", "no_opening_balance", "before_opening_balance", "file_balance_inconsistent" ] }, "file_opening_minor": { "type": [ "integer", "null" ] }, "file_opening_on": { "type": [ "string", "null" ] }, "ledger_balance_minor": { "type": [ "integer", "null" ] }, "gap_minor": { "type": [ "integer", "null" ] }, "gap_from": { "type": [ "string", "null" ] }, "gap_to": { "type": [ "string", "null" ] } }, "required": [ "status", "reason", "file_opening_minor", "file_opening_on", "ledger_balance_minor", "gap_minor", "gap_from", "gap_to" ] }, "FinanzasCartolaPreview": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready", "needs_mapping" ] }, "mapping_needed": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "header_row": { "type": [ "integer", "null" ] }, "header": { "type": "array", "items": { "type": "string" } }, "sample": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "guessed": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "reason", "header_row", "header", "sample", "guessed" ] }, "format": { "type": [ "object", "null" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "auto": { "type": "boolean" } }, "required": [ "key", "label", "auto" ] }, "mapping_source": { "type": [ "string", "null" ], "enum": [ "request", "saved", "auto" ] }, "header_row": { "type": [ "integer", "null" ] }, "columns": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "date_from": { "type": [ "string", "null" ] }, "date_to": { "type": [ "string", "null" ] }, "counts": { "type": [ "object", "null" ], "properties": { "rows_read": { "type": "integer" }, "new": { "type": "integer" }, "duplicate": { "type": "integer" }, "rejected": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "rows_read", "new", "duplicate", "rejected", "skipped" ] }, "totals": { "type": [ "object", "null" ], "properties": { "inbound_minor": { "type": "integer" }, "outbound_minor": { "type": "integer" } }, "required": [ "inbound_minor", "outbound_minor" ] }, "balance": { "type": [ "object", "null" ], "properties": { "has_balance": { "type": "boolean" }, "opening_minor": { "type": [ "integer", "null" ] }, "closing_minor": { "type": [ "integer", "null" ] }, "chain_breaks": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "expected_minor": { "type": "integer" }, "found_minor": { "type": "integer" } }, "required": [ "date", "expected_minor", "found_minor" ] } } }, "required": [ "has_balance", "opening_minor", "closing_minor", "chain_breaks" ] }, "continuity": { "$ref": "#/components/schemas/FinanzasCartolaContinuity" }, "rejections": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "row", "reason" ] } }, "movements": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "date": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "amount_minor": { "type": "integer" }, "description": { "type": "string" }, "balance_minor": { "type": [ "integer", "null" ] }, "duplicate": { "type": "boolean" } }, "required": [ "row", "date", "direction", "amount_minor", "description", "balance_minor", "duplicate" ] } }, "movements_truncated": { "type": "boolean" }, "currency": { "type": "string", "enum": [ "CLP", "USD" ] } }, "required": [ "status", "mapping_needed", "format", "mapping_source", "header_row", "columns", "date_from", "date_to", "counts", "totals", "balance", "continuity", "rejections", "movements", "movements_truncated", "currency" ] }, "FinanzasCartolaImportResult": { "type": "object", "properties": { "import": { "type": "object", "properties": { "id": { "type": "string" }, "file_name": { "type": "string" }, "format": { "type": "string" }, "date_from": { "type": "string" }, "date_to": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "file_name", "format", "date_from", "date_to", "created_at" ] }, "counts": { "type": "object", "properties": { "rows_read": { "type": "integer" }, "new": { "type": "integer" }, "duplicate": { "type": "integer" }, "rejected": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "rows_read", "new", "duplicate", "rejected", "skipped" ] }, "rejections": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "row", "reason" ] } }, "continuity": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCartolaContinuity" }, { "type": "object" } ] }, "gap_accepted": { "type": "boolean" }, "closing_gap_minor": { "type": [ "integer", "null" ] }, "mapping_saved": { "type": "boolean" }, "account": { "description": "FinanzasBankAccount, refreshed." } }, "required": [ "import", "counts", "rejections", "continuity", "gap_accepted", "closing_gap_minor", "mapping_saved" ] }, "FinanzasCartolaImportRecord": { "type": "object", "properties": { "id": { "type": "string" }, "bank_account_id": { "type": "string" }, "file_name": { "type": "string" }, "format": { "type": "string" }, "date_from": { "type": "string" }, "date_to": { "type": "string" }, "rows_read": { "type": "integer" }, "rows_new": { "type": "integer" }, "rows_duplicate": { "type": "integer" }, "rows_rejected": { "type": "integer" }, "opening_minor": { "type": [ "integer", "null" ] }, "closing_minor": { "type": [ "integer", "null" ] }, "gap_minor": { "type": [ "integer", "null" ] }, "gap_accepted": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "bank_account_id", "file_name", "format", "date_from", "date_to", "rows_read", "rows_new", "rows_duplicate", "rows_rejected", "opening_minor", "closing_minor", "gap_minor", "gap_accepted", "created_at" ] }, "FinanzasItemType": { "type": "string", "enum": [ "document", "movement" ] }, "FinanzasClassificationSource": { "type": [ "string", "null" ], "enum": [ "manual", "rule", "ia", "chipax" ] }, "FinanzasClassificationSummaries": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FinanzasItemType" }, "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "unclassified", "classified" ] }, "source": { "$ref": "#/components/schemas/FinanzasClassificationSource" }, "rule": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] } }, "split": { "type": "boolean" } }, "required": [ "type", "id", "state", "source", "rule", "accounts", "split" ] } } }, "required": [ "items" ] }, "FinanzasClassification": { "type": "object", "properties": { "item": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FinanzasItemType" }, "id": { "type": "string", "format": "uuid" }, "amount_clp": { "type": "integer" }, "day": { "type": "string" }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "counterparty_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ] }, "document_kind": { "type": [ "string", "null" ] }, "expense_document_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type", "id", "amount_clp", "day", "contraparte", "counterparty_name", "description", "direction", "document_kind", "expense_document_id" ] }, "state": { "type": "string", "enum": [ "unclassified", "classified" ] }, "source": { "$ref": "#/components/schemas/FinanzasClassificationSource" }, "rule": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "account": { "$ref": "#/components/schemas/FinanzasAccountRef" }, "amount_clp": { "type": "integer" }, "period": { "type": "string" }, "source": { "allOf": [ { "$ref": "#/components/schemas/FinanzasClassificationSource" }, { "type": "string" } ] }, "rule": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "classified_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "account", "amount_clp", "period", "source", "rule", "classified_by", "created_at" ] } }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "enum": [ "classify", "reclassify", "unclassify" ] }, "actor": { "type": "string", "enum": [ "user", "rule", "ia", "chipax" ] }, "actor_user_id": { "type": [ "string", "null" ] }, "rule_id": { "type": [ "string", "null" ], "format": "uuid" }, "before": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "amount_clp": { "type": "integer" }, "period": { "type": "string" } }, "required": [ "account_id", "amount_clp", "period" ] } }, "after": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "amount_clp": { "type": "integer" }, "period": { "type": "string" } }, "required": [ "account_id", "amount_clp", "period" ] } }, "created_at": { "type": "string" } }, "required": [ "id", "action", "actor", "actor_user_id", "rule_id", "before", "after", "created_at" ] } } }, "required": [ "item", "state", "source", "rule", "lines" ] }, "FinanzasClassifyBody": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The account of the plan de cuentas. Or name it with `account_name`." }, "account_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300, "description": "Plain-language alternative to `account_id`: the account name or path («Laboratorio», «Gastos de administración › Arriendo»), matched without case or accents. Ambiguous → 422 `account_ambiguous` with `details.candidates`." }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "Accrual month, `YYYY-MM`.", "example": "2026-10" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The account of the plan de cuentas. Or name it with `account_name`." }, "account_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300, "description": "Plain-language alternative to `account_id`: the account name or path («Laboratorio», «Gastos de administración › Arriendo»), matched without case or accents. Ambiguous → 422 `account_ambiguous` with `details.candidates`." }, "amount_clp": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Whole CLP. Required when there is more than one line." }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "Accrual month, `YYYY-MM`.", "example": "2026-10" } }, "additionalProperties": false }, "minItems": 1, "maxItems": 50, "description": "The split («Dividir»): lines summing EXACTLY to the item total (whole pesos; a remainder is refused). Omit for one line with the whole amount on `account_id` / `account_name`." } }, "additionalProperties": false }, "FinanzasItemRef": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FinanzasItemType" }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ], "additionalProperties": false }, "FinanzasBulkClassifyResult": { "type": "object", "properties": { "classified": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasItemRef" } } }, "required": [ "classified", "items" ] }, "FinanzasBulkClassifyBody": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasItemRef" }, "minItems": 1, "maxItems": 500 }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The account of the plan de cuentas. Or name it with `account_name`." }, "account_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300, "description": "Plain-language alternative to `account_id`: the account name or path («Laboratorio», «Gastos de administración › Arriendo»), matched without case or accents. Ambiguous → 422 `account_ambiguous` with `details.candidates`." }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "Accrual month for every item; default each item’s own month.", "example": "2026-10" } }, "required": [ "items" ], "additionalProperties": false }, "FinanzasExpensesResult": { "type": "object", "properties": { "count": { "type": "integer" }, "expenses": { "type": "array", "items": { "type": "object", "properties": { "movement_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "amount_clp": { "type": "integer" }, "day": { "type": "string" } }, "required": [ "movement_id", "document_id", "amount_clp", "day" ] } } }, "required": [ "count", "expenses" ] }, "FinanzasExpensesFromMovementsBody": { "type": "object", "properties": { "movement_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500 }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The account of the plan de cuentas. Or name it with `account_name`." }, "account_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300, "description": "Plain-language alternative to `account_id`: the account name or path («Laboratorio», «Gastos de administración › Arriendo»), matched without case or accents. Ambiguous → 422 `account_ambiguous` with `details.candidates`." }, "description": { "type": [ "string", "null" ], "maxLength": 300, "description": "Shared description; default each movement’s bank text." }, "period": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "description": "Accrual month for every gasto; default each movement’s month.", "example": "2026-10" } }, "required": [ "movement_ids" ], "additionalProperties": false }, "FinanzasRules": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasRule" } } }, "required": [ "rules" ] }, "FinanzasRuleCreateBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 120 }, "contraparte_id": { "type": [ "string", "null" ], "format": "uuid" }, "contraparte_rut": { "type": [ "string", "null" ], "maxLength": 20, "description": "Plain-language alternative to `contraparte_id`: its RUT." }, "contraparte_name": { "type": [ "string", "null" ], "maxLength": 300, "description": "Plain-language alternative to `contraparte_id`: its name. Ambiguous → 422 `contraparte_ambiguous` with `details.candidates`." }, "text_contains": { "type": [ "string", "null" ], "maxLength": 120, "description": "«Descripción contiene»: case- and accent-insensitive substring of the counterparty name (and, on movements, the bank description)." }, "amount_min_clp": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "amount_max_clp": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ], "description": "Movement rules only: inbound = abono, outbound = cargo." }, "document_kind": { "type": [ "string", "null" ], "enum": [ "purchase", "sale", "honorario", "manual_expense", "tax" ], "description": "Document rules only: the register." }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The account of the plan de cuentas. Or name it with `account_name`." }, "account_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300, "description": "Plain-language alternative to `account_id`: the account name or path («Laboratorio», «Gastos de administración › Arriendo»), matched without case or accents. Ambiguous → 422 `account_ambiguous` with `details.candidates`." }, "accrual": { "type": "string", "enum": [ "issue_month", "previous_month" ], "description": "The month the rule books a document in: `issue_month` (its issue date, the default) or `previous_month` («mes anterior»: a supplier that bills month M early in M+1). Vitrina learns it from history; a person setting it here wins for good." }, "target": { "type": "string", "enum": [ "document", "movement" ], "description": "Default `document` (or the type of `from_item`)." }, "from_item": { "allOf": [ { "$ref": "#/components/schemas/FinanzasItemRef" }, { "description": "«Siempre clasificar así»: prefill target, Contraparte (or its name as text), direction and account from this item and its classification. Explicit fields win." } ] } }, "additionalProperties": false }, "FinanzasRuleUpdateBody": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 120 }, "contraparte_id": { "type": [ "string", "null" ], "format": "uuid" }, "contraparte_rut": { "type": [ "string", "null" ], "maxLength": 20, "description": "Plain-language alternative to `contraparte_id`: its RUT." }, "contraparte_name": { "type": [ "string", "null" ], "maxLength": 300, "description": "Plain-language alternative to `contraparte_id`: its name. Ambiguous → 422 `contraparte_ambiguous` with `details.candidates`." }, "text_contains": { "type": [ "string", "null" ], "maxLength": 120, "description": "«Descripción contiene»: case- and accent-insensitive substring of the counterparty name (and, on movements, the bank description)." }, "amount_min_clp": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "amount_max_clp": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ], "description": "Movement rules only: inbound = abono, outbound = cargo." }, "document_kind": { "type": [ "string", "null" ], "enum": [ "purchase", "sale", "honorario", "manual_expense", "tax" ], "description": "Document rules only: the register." }, "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The account of the plan de cuentas. Or name it with `account_name`." }, "account_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300, "description": "Plain-language alternative to `account_id`: the account name or path («Laboratorio», «Gastos de administración › Arriendo»), matched without case or accents. Ambiguous → 422 `account_ambiguous` with `details.candidates`." }, "accrual": { "type": "string", "enum": [ "issue_month", "previous_month" ], "description": "The month the rule books a document in: `issue_month` (its issue date, the default) or `previous_month` («mes anterior»: a supplier that bills month M early in M+1). Vitrina learns it from history; a person setting it here wins for good." }, "target": { "type": "string", "enum": [ "document", "movement" ], "description": "`document`: classifies documents. `movement`: classifies bank movements that have no document (a gardener paid by transfer)." } }, "additionalProperties": false }, "FinanzasRulePending": { "type": "object", "properties": { "rule_id": { "type": "string", "format": "uuid" }, "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "sample": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/FinanzasItemType" }, "id": { "type": "string", "format": "uuid" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "counterparty_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] } }, "required": [ "type", "id", "day", "amount_clp", "counterparty_name", "description" ] } } }, "required": [ "rule_id", "count", "total_clp", "sample" ] }, "FinanzasRuleApplyResult": { "type": "object", "properties": { "rule_id": { "type": "string", "format": "uuid" }, "applied": { "type": "integer" } }, "required": [ "rule_id", "applied" ] }, "FinanzasTransferAccount": { "type": [ "object", "null" ], "properties": { "bank_account_id": { "type": [ "string", "null" ], "description": "The Finanzas bank account; null for an own account Vitrina does not hold (not connected or not registered yet)." }, "institution_name": { "type": [ "string", "null" ] }, "last4": { "type": [ "string", "null" ] }, "label": { "type": "string", "description": "Ready to show: «BCI ··9819», «Cuenta ··4521» without a bank." } }, "required": [ "bank_account_id", "institution_name", "last4", "label" ], "description": "The side the money left; null = an own account Vitrina does not hold." }, "FinanzasOwnTransfer": { "type": [ "object", "null" ], "properties": { "from": { "$ref": "#/components/schemas/FinanzasTransferAccount" }, "to": { "allOf": [ { "$ref": "#/components/schemas/FinanzasTransferAccount" }, { "description": "The side the money reached; null = an own account Vitrina does not hold." } ] }, "paired_movement_id": { "type": [ "string", "null" ], "description": "The movement on the other side, when Vitrina holds it (link to it)." } }, "required": [ "from", "to", "paired_movement_id" ], "description": "Only on `target = transfer`: «Traspaso entre tus cuentas», both sides ready to show." }, "FinanzasLink": { "type": "object", "properties": { "id": { "type": "string" }, "target": { "type": "string", "enum": [ "document", "payment", "transfer", "third_party", "cash_deposit" ] }, "amount_clp": { "type": "integer" }, "rounding_clp": { "type": "integer", "description": "Pesos the document was credited beyond `amount_clp` (negative when the movement paid more); |x| ≤ 10, only on a matcher link of a known supplier (reason `rounding`). 0 = exact. The document is paid by `amount_clp + rounding_clp`; the movement explains `amount_clp`." }, "actor": { "type": "string", "enum": [ "person", "rule", "match", "ai", "import" ], "description": "person = Manual, rule = Regla, match = Coincidencia, ai = IA, import = Importación (copied from Chipax, Finanzas 16; reason `chipax_import`)." }, "actor_user_id": { "type": [ "string", "null" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "undone_at": { "type": [ "string", "null" ] }, "movement_id": { "type": "string" }, "document": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "total_clp": { "type": "integer" }, "counterparty_name": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "dte_type", "folio", "issue_date", "total_clp", "counterparty_name" ] }, "payment": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "id", "day", "amount_clp", "patient" ] }, "paired_movement": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "direction": { "type": [ "string", "null" ] }, "bank_account_name": { "type": [ "string", "null" ] } }, "required": [ "id", "day", "amount_clp", "direction", "bank_account_name" ] }, "cash_day": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" } }, "required": [ "id", "day", "amount_clp" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "payout": { "type": [ "object", "null" ], "properties": { "movement_id": { "type": "string" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "processor_name": { "type": [ "string", "null" ] } }, "required": [ "movement_id", "day", "amount_clp", "processor_name" ], "description": "Finanzas 36: set on a link with reason `payout_deduction`: the commission factura (`document`) was paid by deduction from this card payout (the processor kept it). Show «Pagada con descuento» and «Descontada del abono de {processor_name} del {day}», linking to `movement_id`. Such a link takes nothing from the payout's cash. Null otherwise." }, "own_transfer": { "$ref": "#/components/schemas/FinanzasOwnTransfer" }, "undoable": { "type": "boolean" } }, "required": [ "id", "target", "amount_clp", "rounding_clp", "actor", "actor_user_id", "reasons", "note", "created_at", "undone_at", "movement_id", "document", "payment", "paired_movement", "cash_day", "contraparte", "payout", "own_transfer", "undoable" ] }, "FinanzasLegacyLink": { "type": "object", "properties": { "id": { "type": "string", "description": "`settlement:` or `payment:`." }, "kind": { "type": "string", "enum": [ "settlement", "payment" ] }, "target": { "type": "string", "enum": [ "payment" ] }, "amount_clp": { "type": "integer" }, "actor": { "type": "string", "enum": [ "person", "match" ] }, "created_at": { "type": "string" }, "detail": { "type": "object", "properties": { "settlement_kind": { "type": "string" }, "business_day": { "type": "string" }, "commission_clp": { "type": "integer" }, "payment_ids": { "type": "array", "items": { "type": "string" } }, "paid_on": { "type": [ "string", "null" ] }, "instrument": { "type": [ "string", "null" ] } } }, "undoable": { "type": "boolean" } }, "required": [ "id", "kind", "target", "amount_clp", "actor", "created_at", "detail", "undoable" ] }, "FinanzasMovementReconciliation": { "type": "object", "properties": { "movement": { "$ref": "#/components/schemas/FinanzasMovement" }, "money_mirrored": { "type": "boolean", "description": "The clinic money of this movement is mirrored from its clinic system: it links only to those payments, as evidence." }, "payer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] } }, "required": [ "name", "email", "patient" ] }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasLink" } }, "legacy_links": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasLegacyLink" } }, "commission": { "type": [ "object", "null" ], "properties": { "amount_clp": { "type": "integer" }, "source": { "type": "string", "enum": [ "mercado_pago", "card_settlement" ] }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "amount_clp", "source", "account" ] } }, "required": [ "movement", "money_mirrored", "payer", "links", "legacy_links", "commission" ] }, "FinanzasMovementCandidates": { "type": "object", "properties": { "pending_clp": { "type": "integer" }, "money_mirrored": { "type": "boolean" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "total_clp": { "type": "integer" }, "outstanding_clp": { "type": "integer" }, "counterparty_name": { "type": [ "string", "null" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "signal": { "type": [ "string", "null" ], "enum": [ "folio", "contraparte", "amount", "search" ] }, "suggested_amount_clp": { "type": "integer" } }, "required": [ "id", "kind", "dte_type", "folio", "issue_date", "due_date", "total_clp", "outstanding_clp", "counterparty_name", "contraparte", "signal", "suggested_amount_clp" ] } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "caja", "mirror" ] }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "instrument": { "type": [ "string", "null" ] }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] } }, "required": [ "id", "source", "day", "amount_clp", "instrument", "patient" ] } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer" }, "bank_account_name": { "type": [ "string", "null" ] }, "description": { "type": "string" } }, "required": [ "id", "day", "direction", "amount_clp", "bank_account_name", "description" ] } }, "cash_days": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "source": { "type": "string", "enum": [ "caja", "boletas" ] }, "remaining_clp": { "type": "integer" } }, "required": [ "id", "day", "source", "remaining_clp" ] } } }, "required": [ "pending_clp", "money_mirrored", "documents", "payments", "transfers", "cash_days" ] }, "FinanzasDocumentReconciliation": { "type": "object", "properties": { "document": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "counterparty_name": { "type": [ "string", "null" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "total_clp": { "type": "integer" }, "paid_clp": { "type": "integer" }, "outstanding_clp": { "type": "integer" }, "payment_state": { "type": "string", "enum": [ "por_pagar", "parcial", "pagado", "vencido_heredado" ], "description": "`vencido_heredado` is retired (Finanzas 50): only rows written before it, outside that backfill, still carry it." } }, "required": [ "id", "kind", "dte_type", "folio", "issue_date", "due_date", "counterparty_name", "contraparte", "total_clp", "paid_clp", "outstanding_clp", "payment_state" ] }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasLink" } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer" }, "pending_clp": { "type": "integer" }, "description": { "type": "string" }, "counterparty_name": { "type": [ "string", "null" ] }, "bank_account_name": { "type": [ "string", "null" ] }, "signal": { "type": "string", "enum": [ "folio", "contraparte", "amount", "search" ] }, "suggested_amount_clp": { "type": "integer" } }, "required": [ "id", "day", "direction", "amount_clp", "pending_clp", "description", "counterparty_name", "bank_account_name", "signal", "suggested_amount_clp" ] } } }, "required": [ "document", "links", "candidates" ] }, "FinanzasEngineResult": { "type": "object", "properties": { "skipped": { "type": "boolean" }, "from": { "type": "string" }, "to": { "type": "string" }, "movements_seen": { "type": "integer" }, "applied": { "type": "object", "properties": { "documents": { "type": "integer" }, "transfers": { "type": "integer" }, "cash_deposits": { "type": "integer" }, "payments": { "type": "integer" }, "expenses": { "type": "integer", "description": "Gastos created from a movement («Crear gasto») linked to it." } }, "required": [ "documents", "transfers", "cash_deposits", "payments", "expenses" ] }, "ambiguous": { "type": "integer" } }, "required": [ "skipped", "from", "to", "movements_seen", "applied", "ambiguous" ] }, "FinanzasCashPending": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "source": { "type": "string", "enum": [ "caja", "boletas" ] }, "amount_clp": { "type": "integer" }, "deposited_clp": { "type": "integer" }, "remaining_clp": { "type": "integer" }, "detail": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "id", "day", "source", "amount_clp", "deposited_clp", "remaining_clp", "detail" ] } }, "total_remaining_clp": { "type": "integer" }, "pending": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashPendingSummary" }, { "description": "The one «efectivo por depositar» (last 60 days up to yesterday), identical to the Flujo de caja and Movimientos. `items` is the standing list for the requested period (it feeds the Por resolver matcher)." } ] } }, "required": [ "items", "total_remaining_clp", "pending" ] }, "FinanzasCommissions": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "movement_id": { "type": "string" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "source": { "type": "string", "enum": [ "mercado_pago", "card_settlement" ] }, "bank_account_name": { "type": [ "string", "null" ] }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "movement_id", "day", "amount_clp", "source", "bank_account_name", "account" ] } }, "total_clp": { "type": "integer" } }, "required": [ "items", "total_clp" ] }, "FinanzasCaseList": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "reconcile", "transfer", "classify", "missing_document", "unknown", "ads_charge", "merge" ], "description": "reconcile = movements ↔ documents; transfer = between own accounts; classify = to an account; missing_document = «Falta documento» (money out classified with no document); unknown = no proposal yet; ads_charge = a Meta / Google card charge Vitrina could not confirm («Cargo de publicidad sin confirmar» / «Sin conexión de publicidad», Finanzas 30): the proposal links each movement to its own ads document; merge = a «unir» Caso (Finanzas 58): two Contrapartes with similar names and no shared RUT, proposed to be merged (`merge` holds the pair; it has no movements or documents and moves no money)." }, "title": { "type": "string" }, "summary": { "type": "string" }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "rut": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut" ] }, "amount_at_stake_clp": { "type": "integer" }, "item_count": { "type": "integer" }, "movement_count": { "type": "integer" }, "document_count": { "type": "integer" }, "ready": { "type": "boolean" }, "opened_at": { "type": "string" }, "latest_day": { "type": [ "string", "null" ], "description": "The newest day the case touches (a movement, or a document it needs classified)." }, "fingerprint": { "type": "string", "description": "The case as listed; «Confirmar en bloque» sends it back (a changed case is refused)." } }, "required": [ "id", "kind", "title", "summary", "contraparte", "amount_at_stake_clp", "item_count", "movement_count", "document_count", "ready", "opened_at", "latest_day", "fingerprint" ] } }, "total": { "type": "integer" }, "amount_at_stake_clp": { "type": "integer" }, "since": { "type": "string", "description": "First day of last month: `period=recent` keeps the cases touching it or later; older ones are «Historial»." }, "counts_by_month": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`." }, "open": { "type": "integer" }, "amount_clp": { "type": "integer" } }, "required": [ "month", "open", "amount_clp" ] }, "description": "Open cases per month, newest first, all kinds, ignoring `kind`/`month`/`period`: the month filter’s options (the sum is the open total every surface shows). Months «Cerrado antes de Vitrina» are never listed: they hold no case." }, "counts": { "type": "object", "properties": { "recent": { "type": "integer" }, "history": { "type": "integer" }, "needs_person": { "type": "integer" }, "ready": { "type": "integer" } }, "required": [ "recent", "history", "needs_person", "ready" ], "description": "Open cases by period (every period) and, within the `period` asked, how many need a person vs are ready to confirm." }, "waiting": { "type": "object", "properties": { "count": { "type": "integer" }, "amount_clp": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "movement_id": { "type": "string" }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "lag_days": { "type": "integer" }, "wait_until": { "type": [ "string", "null" ] } }, "required": [ "movement_id", "day", "amount_clp", "contraparte", "lag_days", "wait_until" ] } } }, "required": [ "count", "amount_clp", "items" ], "description": "«Esperando factura»: payments to a supplier that always invoices, inside its usual wait for the document. No case and no classification until then (the factura links instead); after `wait_until` the payment opens a case asking for it." } }, "required": [ "items", "total", "amount_at_stake_clp", "since", "counts_by_month", "counts", "waiting" ] }, "FinanzasCaseCount": { "type": "object", "properties": { "open": { "type": "integer" }, "amount_at_stake_clp": { "type": "integer" }, "by_kind": { "type": "object", "properties": { "reconcile": { "type": "integer" }, "transfer": { "type": "integer" }, "classify": { "type": "integer" }, "missing_document": { "type": "integer" }, "unknown": { "type": "integer" }, "ads_charge": { "type": "integer" }, "merge": { "type": "integer" } }, "required": [ "reconcile", "transfer", "classify", "missing_document", "unknown", "ads_charge", "merge" ] } }, "required": [ "open", "amount_at_stake_clp", "by_kind" ] }, "FinanzasCase": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "reconcile", "transfer", "classify", "missing_document", "unknown", "ads_charge", "merge" ], "description": "reconcile = movements ↔ documents; transfer = between own accounts; classify = to an account; missing_document = «Falta documento» (money out classified with no document); unknown = no proposal yet; ads_charge = a Meta / Google card charge Vitrina could not confirm («Cargo de publicidad sin confirmar» / «Sin conexión de publicidad», Finanzas 30): the proposal links each movement to its own ads document; merge = a «unir» Caso (Finanzas 58): two Contrapartes with similar names and no shared RUT, proposed to be merged (`merge` holds the pair; it has no movements or documents and moves no money)." }, "status": { "type": "string", "enum": [ "open", "resolved" ] }, "resolution": { "type": [ "string", "null" ], "enum": [ "confirmed", "cleared", "closed_imported" ] }, "resolved_at": { "type": [ "string", "null" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "rut": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut" ] }, "title": { "type": "string" }, "summary": { "type": "string" }, "amount_at_stake_clp": { "type": "integer" }, "item_count": { "type": "integer" }, "ready": { "type": "boolean", "description": "Every item has a proposed action: «Resolver» (POST …/confirm) clears the whole case." }, "fingerprint": { "type": "string" }, "movements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer" }, "pending_clp": { "type": "integer" }, "description": { "type": "string" }, "counterparty_name": { "type": [ "string", "null" ] }, "bank_account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "role": { "type": "string", "enum": [ "open", "missing_document" ] }, "classification": { "type": [ "object", "null" ], "properties": { "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] } }, "required": [ "account" ] } }, "required": [ "id", "day", "direction", "amount_clp", "pending_clp", "description", "counterparty_name", "bank_account", "role", "classification" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "purchase", "sale", "honorario", "manual_expense", "tax" ] }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "due_date": { "type": [ "string", "null" ] }, "total_clp": { "type": "integer", "description": "What is paid: the líquido on a boleta de honorarios, the total otherwise." }, "gross_clp": { "type": "integer", "description": "What the document costs: the gross total. Differs from total_clp only on a boleta de honorarios." }, "outstanding_clp": { "type": "integer" }, "counterparty_name": { "type": [ "string", "null" ] }, "role": { "type": "string", "enum": [ "unclassified", "candidate" ] }, "classified": { "type": "boolean" } }, "required": [ "id", "kind", "dte_type", "folio", "issue_date", "due_date", "total_clp", "gross_clp", "outstanding_clp", "counterparty_name", "role", "classified" ] } }, "cash_days": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "day": { "type": "string" }, "remaining_clp": { "type": "integer" } }, "required": [ "id", "day", "remaining_clp" ] } }, "proposal": { "type": "object", "properties": { "actions": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "link" ] }, "movement_id": { "type": "string" }, "links": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "target": { "type": "string", "enum": [ "document" ] }, "document_id": { "type": "string" }, "amount_clp": { "type": "integer" } }, "required": [ "target", "document_id", "amount_clp" ] }, { "type": "object", "properties": { "target": { "type": "string", "enum": [ "transfer" ] }, "paired_movement_id": { "type": "string" } }, "required": [ "target", "paired_movement_id" ] }, { "type": "object", "properties": { "target": { "type": "string", "enum": [ "cash_deposit" ] }, "cash_day_id": { "type": "string" }, "amount_clp": { "type": "integer" } }, "required": [ "target", "cash_day_id", "amount_clp" ] } ] } }, "replace_classification": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Stable codes: folio_and_amount, exact_amount, sum_of_documents, sum_of_movements, nearest_date (a pago a cuenta on the documents issued nearest the payment; cases built before 2026-11 may carry oldest_first), cash_deposit, own_account_transfer, history, document_arrived, no_document, ia (the IA proposed it: below the auto-apply threshold, or the IA switch is off)." } }, "required": [ "type", "movement_id", "links", "replace_classification", "reasons" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "classify" ] }, "item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "movement" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Stable codes: folio_and_amount, exact_amount, sum_of_documents, sum_of_movements, nearest_date (a pago a cuenta on the documents issued nearest the payment; cases built before 2026-11 may carry oldest_first), cash_deposit, own_account_transfer, history, document_arrived, no_document, ia (the IA proposed it: below the auto-apply threshold, or the IA switch is off)." } }, "required": [ "type", "item", "account", "reasons" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "accept_without_document" ] }, "movement_id": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Stable codes: folio_and_amount, exact_amount, sum_of_documents, sum_of_movements, nearest_date (a pago a cuenta on the documents issued nearest the payment; cases built before 2026-11 may carry oldest_first), cash_deposit, own_account_transfer, history, document_arrived, no_document, ia (the IA proposed it: below the auto-apply threshold, or the IA switch is off)." } }, "required": [ "type", "movement_id", "reasons" ] } ] } }, "why": { "type": "array", "items": { "type": "string" }, "description": "Spanish sentences: why Vitrina proposes this." } }, "required": [ "actions", "why" ] }, "unresolved": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "movement" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } }, "awaiting_document": { "type": "array", "items": { "type": "string" }, "description": "Movement ids of payments to a supplier that always invoices, past its usual wait: the factura is missing. Never classified on their own nor asked to the IA." }, "ads": { "type": [ "object", "null" ], "properties": { "platform": { "type": "string", "enum": [ "meta_ads", "google_ads" ] }, "verdict": { "type": "string", "enum": [ "unconfirmed", "no_connection" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "movement_id": { "type": "string", "format": "uuid" }, "document_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "description": "no_charge | count_mismatch | customer_id_unknown | spend_does_not_cover | ambiguous | refund_unmatched | undone_by_person | no_connection" }, "customer_id": { "type": [ "string", "null" ] }, "reference": { "type": [ "string", "null" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "charge_id": { "type": "string", "format": "uuid" }, "ad_account_id": { "type": "string" }, "meta_transaction_id": { "type": [ "string", "null" ] }, "event_time": { "type": "string" }, "local_date": { "type": "string" }, "amount_minor": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "charge_id", "ad_account_id", "meta_transaction_id", "event_time", "local_date", "amount_minor", "currency" ] } }, "candidate_accounts": { "type": "array", "items": { "type": "string" } } }, "required": [ "movement_id", "document_id", "reason", "customer_id", "reference", "candidates", "candidate_accounts" ] } } }, "required": [ "platform", "verdict", "items" ], "description": "Finanzas 30, `ads_charge` cases only: the matcher's verdict per movement and the Meta charges / ad accounts that could be it. Amounts in the smallest unit of `currency`." }, "merge": { "type": [ "object", "null" ], "properties": { "keep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut": { "type": [ "string", "null" ] }, "movement_count": { "type": "integer" }, "document_count": { "type": "integer" } }, "required": [ "id", "name", "rut", "movement_count", "document_count" ] }, "merge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut": { "type": [ "string", "null" ] }, "movement_count": { "type": "integer" }, "document_count": { "type": "integer" } }, "required": [ "id", "name", "rut", "movement_count", "document_count" ] }, "score": { "type": "number" }, "moves": { "type": "object", "properties": { "movements": { "type": "integer" }, "documents": { "type": "integer" } }, "required": [ "movements", "documents" ] } }, "required": [ "keep", "merge", "score", "moves" ], "description": "Finanzas 58, `merge` («unir») cases only: the pair. `keep` stays, `merge` is merged into it; `moves` is what passes to `keep`. Resolve with the confirm route (merge, undoable in «Hecho por Vitrina») or the dismiss route («No son la misma»)." }, "opened_at": { "type": "string" }, "computed_at": { "type": "string" } }, "required": [ "id", "key", "kind", "status", "resolution", "resolved_at", "contraparte", "title", "summary", "amount_at_stake_clp", "item_count", "ready", "fingerprint", "movements", "documents", "cash_days", "proposal", "unresolved", "opened_at", "computed_at" ] }, "FinanzasCasesBulkConfirmResult": { "type": "object", "properties": { "confirmed": { "type": "array", "items": { "type": "object", "properties": { "case_id": { "type": "string" }, "applied": { "type": "object", "properties": { "links": { "type": "integer" }, "classifications": { "type": "integer" }, "accepted": { "type": "integer" } }, "required": [ "links", "classifications", "accepted" ] } }, "required": [ "case_id", "applied" ] } }, "failed": { "type": "array", "items": { "type": "object", "properties": { "case_id": { "type": "string" }, "reason": { "type": "string", "description": "resolved | fingerprint_mismatch | proposal_incomplete | refused" }, "message": { "type": "string" } }, "required": [ "case_id", "reason", "message" ] } } }, "required": [ "confirmed", "failed" ] }, "FinanzasCasesBulkConfirmBody": { "type": "object", "properties": { "cases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "fingerprint": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "fingerprint" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100, "description": "The ready cases to confirm with their own proposals, with the fingerprint each was read with." } }, "required": [ "cases" ], "additionalProperties": false }, "FinanzasCaseConfirmResult": { "type": "object", "properties": { "case_id": { "type": "string" }, "applied": { "type": "object", "properties": { "links": { "type": "integer" }, "classifications": { "type": "integer" }, "accepted": { "type": "integer" } }, "required": [ "links", "classifications", "accepted" ] }, "remaining_case": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCase" }, { "type": [ "object", "null" ] } ] }, "next_case_id": { "type": [ "string", "null" ] }, "merged": { "type": "object", "properties": { "merge_id": { "type": "string" }, "survivor_id": { "type": "string" }, "merged_id": { "type": "string" } }, "required": [ "merge_id", "survivor_id", "merged_id" ], "description": "Finanzas 58, `merge` («unir») cases only: the merge the confirm made. `merge_id` is the «Deshacer» id in «Hecho por Vitrina»." }, "descriptors": { "type": "array", "items": { "type": "object", "properties": { "descriptor": { "type": "string" }, "contraparte_id": { "type": "string" }, "status": { "type": "string", "enum": [ "learned", "forgotten" ] } }, "required": [ "descriptor", "contraparte_id", "status" ] }, "description": "Card / automatic-debit descriptors this confirm tied to a Contraparte (`learned`: a movement that named no RUT or account was confirmed against documents of one Contraparte; from now on the engine knows the supplier, shown once as «Desde ahora reconocemos “MERPAGO*MERCADOL” como …»), or untied (`forgotten`: confirmed for a second Contraparte, so it names neither). Listed and removable as the Contraparte's aliases (kind `descriptor`)." } }, "required": [ "case_id", "applied", "remaining_case", "next_case_id", "descriptors" ] }, "FinanzasCaseDismissResult": { "type": "object", "properties": { "case_id": { "type": "string" }, "next_case_id": { "type": [ "string", "null" ] } }, "required": [ "case_id", "next_case_id" ] }, "FinanzasNoDocumentUndo": { "type": "object", "properties": { "movement_id": { "type": "string" }, "case_id": { "type": [ "string", "null" ] } }, "required": [ "movement_id", "case_id" ] }, "FinanzasAutomaticAction": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link", "classification" ], "description": "link = a reconciliation link (Finanzas 08); classification = a classification by a rule or the IA (Finanzas 07)." }, "id": { "type": "string", "format": "uuid" }, "actor": { "type": "string", "enum": [ "rule", "match", "ai" ], "description": "rule = Regla, match = Coincidencia, ai = IA." }, "label": { "type": "string", "description": "What Vitrina did, one Spanish sentence." }, "day": { "type": "string", "description": "The item's day, `YYYY-MM-DD`." }, "amount_clp": { "type": "integer" }, "applied_at": { "type": "string" }, "movement": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "day": { "type": "string" }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer" }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "day", "direction", "amount_clp", "description" ] }, "document": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "total_clp": { "type": "integer" }, "counterparty_name": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "dte_type", "folio", "issue_date", "total_clp", "counterparty_name" ] }, "target": { "type": [ "string", "null" ], "enum": [ "document", "payment", "transfer", "third_party", "cash_deposit" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": [ "string", "null" ], "description": "Links Vitrina made from ad data (Finanzas 30, reasons include `ads_charge`): the evidence in one Spanish line, e.g. «Meta Ads cobró $4.211 el 22 oct a las 09:14 (cuenta …)» or «Gasto del 22 al 24 oct: $47.824 en la cuenta … de Google Ads; el cargo lo cubre». A matcher link of a known supplier within rounding (reason `rounding`) or paid before its document was issued (`paid_before_issue`) says so here, e.g. «El pago fue $1 menor que el documento; la diferencia quedó como redondeo y el documento se cerró.». Null otherwise." }, "own_transfer": { "allOf": [ { "$ref": "#/components/schemas/FinanzasOwnTransfer" }, { "description": "Only on a `transfer` link (Finanzas 32, D5): «BCI ··9819 → Itaú ··9627», with the paired movement when Vitrina holds it. Null otherwise." } ] }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] }, "split": { "type": "boolean" }, "rule": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "reviewed_at": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] } }, "required": [ "kind", "id", "actor", "label", "day", "amount_clp", "applied_at", "movement", "document", "target", "reasons", "evidence", "own_transfer", "account", "split", "rule", "reviewed_at", "reviewed_by" ] }, "FinanzasAutomaticActions": { "type": "object", "properties": { "month": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "unreviewed_count": { "type": "integer" }, "by_actor": { "type": "object", "properties": { "rule": { "type": "integer" }, "match": { "type": "integer" }, "ai": { "type": "integer" } }, "required": [ "rule", "match", "ai" ] }, "contraparte_merges": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasContraparteMergeView" }, "description": "Contrapartes Vitrina (or a person) merged this month, newest first: «Contrapartes unidas» with «Deshacer» (`undoable`) in Hecho por Vitrina." }, "rules_created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] }, "status": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "label", "contraparte", "account", "status", "created_at" ] } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "name": { "type": "string" }, "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "unreviewed_count": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasAutomaticAction" } }, "items_truncated": { "type": "boolean" } }, "required": [ "key", "contraparte", "name", "count", "total_clp", "unreviewed_count", "items", "items_truncated" ] } } }, "required": [ "month", "from", "to", "count", "total_clp", "unreviewed_count", "by_actor", "contraparte_merges", "rules_created", "groups" ] }, "FinanzasAutomaticActionsReview": { "type": "object", "properties": { "reviewed": { "type": "integer" } }, "required": [ "reviewed" ] }, "FinanzasAutomaticActionUndo": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "link", "classification" ], "description": "link = a reconciliation link (Finanzas 08); classification = a classification by a rule or the IA (Finanzas 07)." }, "id": { "type": "string", "format": "uuid" }, "actor": { "type": "string", "enum": [ "rule", "match", "ai" ], "description": "rule = Regla, match = Coincidencia, ai = IA." }, "item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "movement" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ] }, "document_id": { "type": [ "string", "null" ], "format": "uuid" }, "teaching_signal": { "type": "boolean" } }, "required": [ "kind", "id", "actor", "item", "document_id", "teaching_signal" ] }, "FinanzasOwnAccountSuggestion": { "type": "object", "properties": { "key": { "type": "string", "description": "The account number as digits without leading zeros: the id for accept and dismiss." }, "last4": { "type": "string" }, "number_masked": { "type": "string", "description": "«•••• 4521»." }, "bank_name": { "type": [ "string", "null" ], "description": "The destination bank. The bank feeds do not report it for a recipient, so today it is null: show «Cuenta ··4521»." }, "total_clp": { "type": "integer", "description": "Σ of the traspasos that went to this account (live ones only)." }, "count": { "type": "integer" }, "first_day": { "type": "string" }, "last_day": { "type": "string" }, "title": { "type": "string", "description": "«Agregar ··4521 como cuenta propia»." }, "body": { "type": "string", "description": "«Le transferiste $9.950.000 a tu propio RUT. Si la cuenta es tuya, esos traspasos no cuentan como gasto.»" } }, "required": [ "key", "last4", "number_masked", "bank_name", "total_clp", "count", "first_day", "last_day", "title", "body" ] }, "FinanzasOwnAccountSuggestions": { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasOwnAccountSuggestion" } }, "count": { "type": "integer" } }, "required": [ "suggestions", "count" ] }, "FinanzasOwnAccountAcceptBody": { "type": "object", "properties": { "institution_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "description": "The bank, when the person knows it. Optional: one click is enough." }, "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "description": "Default «Cuenta ··‹últimos 4›»." } }, "additionalProperties": false }, "FinanzasOwnAccountDismiss": { "type": "object", "properties": { "key": { "type": "string" }, "dismissed": { "type": "boolean", "enum": [ true ] } }, "required": [ "key", "dismissed" ] }, "FinanzasMonthSummary": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string", "description": "«septiembre 2026»." }, "state": { "type": "string", "enum": [ "open", "ready_to_close", "closed", "closed_imported" ], "description": "open = abierto (cases touch it, or it has not ended); ready_to_close = listo para cerrar; closed = cerrado por una persona; closed_imported = «Cerrado antes de Vitrina» (the import closed it: it raises no cases, a change asks for a reason, there is nothing to close)." }, "ended": { "type": "boolean" }, "open_cases": { "type": "integer", "description": "Open «Por resolver» cases of the month (the month of each case’s oldest item): the one count of open work." }, "open_cases_amount_clp": { "type": "integer", "description": "The money at stake in those cases, whole CLP: the same amount as «Por resolver» with `month`." }, "closed_at": { "type": [ "string", "null" ] }, "closed_by": { "type": [ "string", "null" ] }, "closed_source": { "type": [ "string", "null" ], "enum": [ "person", "chipax" ], "description": "Who closed the month: `person` («Cerrar mes») or `chipax` (the import: «Cerrado antes de Vitrina»). Null while open." }, "imported_at": { "type": [ "string", "null" ], "description": "When the import closed it. Null unless `closed_source` is `chipax`." }, "adjustment_count": { "type": "integer", "description": "Ajustes posteriores al cierre logged so far." } }, "required": [ "month", "label", "state", "ended", "open_cases", "open_cases_amount_clp", "closed_at", "closed_by", "closed_source", "imported_at", "adjustment_count" ] }, "FinanzasMonths": { "type": "object", "properties": { "current_month": { "type": "string" }, "months": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasMonthSummary" } } }, "required": [ "current_month", "months" ] }, "FinanzasMonthStatus": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string", "description": "«septiembre 2026»." }, "state": { "type": "string", "enum": [ "open", "ready_to_close", "closed", "closed_imported" ], "description": "open = abierto (cases touch it, or it has not ended); ready_to_close = listo para cerrar; closed = cerrado por una persona; closed_imported = «Cerrado antes de Vitrina» (the import closed it: it raises no cases, a change asks for a reason, there is nothing to close)." }, "ended": { "type": "boolean" }, "open_cases": { "type": "integer", "description": "Open «Por resolver» cases of the month (the month of each case’s oldest item): the one count of open work." }, "open_cases_amount_clp": { "type": "integer", "description": "The money at stake in those cases, whole CLP: the same amount as «Por resolver» with `month`." }, "closed_at": { "type": [ "string", "null" ] }, "closed_by": { "type": [ "string", "null" ] }, "closed_source": { "type": [ "string", "null" ], "enum": [ "person", "chipax" ], "description": "Who closed the month: `person` («Cerrar mes») or `chipax` (the import: «Cerrado antes de Vitrina»). Null while open." }, "imported_at": { "type": [ "string", "null" ], "description": "When the import closed it. Null unless `closed_source` is `chipax`." }, "adjustment_count": { "type": "integer", "description": "Ajustes posteriores al cierre logged so far." }, "from": { "type": "string" }, "to": { "type": "string" }, "closed_by_name": { "type": [ "string", "null" ] }, "can_close": { "type": "boolean" }, "blocking_reason": { "type": [ "string", "null" ], "enum": [ "open_cases", "not_ended", "already_closed" ] }, "checklist": { "type": "object", "properties": { "open_cases": { "type": "integer", "description": "The headline of «Antes de cerrar» (Finanzas 47): the month’s open Casos. Movements and documents are their detail, never a separate count." }, "open_cases_amount_clp": { "type": "integer", "description": "The money at stake in those cases, whole CLP (= «Por resolver» `?mes=`)." }, "open_case_movements_count": { "type": "integer", "description": "Movements behind the month’s open cases." }, "open_case_documents_count": { "type": "integer", "description": "Documents to classify behind the month’s open cases." }, "unreviewed_count": { "type": "integer", "description": "Automatic actions of the month nobody reviewed in «Hecho por Vitrina». The close confirms this number." }, "unclassified_count": { "type": "integer" }, "unmatched_count": { "type": "integer", "description": "Still to reconcile in the month: bank movements not fully matched plus income documents (boletas, facturas) issued in the month still «Por conciliar» (the same definition as Resultado). Detail, not a headline: what counts as open work is `open_cases`." }, "unmatched_movements_count": { "type": "integer", "description": "Bank movements of the month not fully matched." }, "unmatched_documents_count": { "type": "integer", "description": "Income documents issued in the month still «Por conciliar»." }, "unmatched_pending_clp": { "type": "integer", "description": "What those movements and documents still leave unmatched, whole CLP." }, "unmatched_movements_pending_clp": { "type": "integer" }, "unmatched_documents_pending_clp": { "type": "integer" } }, "required": [ "open_cases", "open_cases_amount_clp", "open_case_movements_count", "open_case_documents_count", "unreviewed_count", "unclassified_count", "unmatched_count", "unmatched_movements_count", "unmatched_documents_count", "unmatched_pending_clp", "unmatched_movements_pending_clp", "unmatched_documents_pending_clp" ] }, "close": { "type": [ "object", "null" ], "properties": { "unreviewed_count": { "type": "integer" }, "unclassified_count": { "type": "integer" }, "unmatched_count": { "type": "integer" }, "snapshot_version": { "type": "integer" }, "snapshot": { "type": "object", "properties": { "documents": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "count", "total_clp" ] } }, "movements": { "type": "object", "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "count", "total_clp" ] } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "account_id", "count", "total_clp" ] } }, "unclassified_documents": { "type": "object", "properties": { "count": { "type": "integer" } }, "required": [ "count" ] }, "unmatched_movements": { "type": "object", "properties": { "count": { "type": "integer" }, "pending_clp": { "type": "integer" } }, "required": [ "count", "pending_clp" ] }, "unmatched_documents": { "type": "object", "properties": { "count": { "type": "integer" }, "pending_clp": { "type": "integer" } }, "required": [ "count", "pending_clp" ], "description": "Income documents still «Por conciliar» at the close (closes made after 2026-10-31)." } }, "required": [ "documents", "movements", "accounts", "unclassified_documents", "unmatched_movements" ], "description": "The month as it was closed (v1): documents by kind, movements by direction, classified totals per account (lines whose accrual month is this one), unclassified and unmatched." } }, "required": [ "unreviewed_count", "unclassified_count", "unmatched_count", "snapshot_version", "snapshot" ] }, "changes_since_close": { "type": [ "object", "null" ], "properties": { "adjustments": { "type": "integer" }, "documents_added": { "type": "integer" }, "documents_voided": { "type": "integer" }, "movements_added": { "type": "integer" } }, "required": [ "adjustments", "documents_added", "documents_voided", "movements_added" ] } }, "required": [ "month", "label", "state", "ended", "open_cases", "open_cases_amount_clp", "closed_at", "closed_by", "closed_source", "imported_at", "adjustment_count", "from", "to", "closed_by_name", "can_close", "blocking_reason", "checklist", "close", "changes_since_close" ] }, "FinanzasPeriodAdjustment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "month": { "type": "string" }, "change": { "type": "string", "enum": [ "classify", "reclassify", "unclassify", "link", "unlink", "accept_without_document", "undo_accept_without_document", "add_document", "edit_document", "remove_document" ] }, "label": { "type": "string", "description": "One Spanish line." }, "actor": { "type": "string", "enum": [ "person", "rule", "match", "ai", "import" ], "description": "person = a person (with `reason`); rule = Regla, match = Coincidencia, ai = IA, import = importación (no reason)." }, "actor_user_id": { "type": [ "string", "null" ] }, "actor_name": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "item": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "movement" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "type", "id" ] }, "document": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "issue_date": { "type": "string" }, "total_clp": { "type": "integer" }, "counterparty_name": { "type": [ "string", "null" ] } }, "required": [ "kind", "dte_type", "folio", "issue_date", "total_clp", "counterparty_name" ] }, "movement": { "type": [ "object", "null" ], "properties": { "day": { "type": "string" }, "direction": { "type": [ "string", "null" ], "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer" }, "description": { "type": "string" } }, "required": [ "day", "direction", "amount_clp", "description" ] }, "before": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] }, "amount_clp": { "type": "integer" }, "period": { "type": "string" } }, "required": [ "account", "amount_clp", "period" ] } }, "after": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] }, "amount_clp": { "type": "integer" }, "period": { "type": "string" } }, "required": [ "account", "amount_clp", "period" ] } }, "amount_clp": { "type": [ "integer", "null" ], "description": "A link: the amount linked or unlinked." }, "created_at": { "type": "string" } }, "required": [ "id", "month", "change", "label", "actor", "actor_user_id", "actor_name", "reason", "item", "document", "movement", "before", "after", "amount_clp", "created_at" ] }, "FinanzasPeriodAdjustments": { "type": "object", "properties": { "month": { "type": "string" }, "closed": { "type": "boolean" }, "closed_at": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasPeriodAdjustment" } } }, "required": [ "month", "closed", "closed_at", "total", "items" ] }, "FinanzasChipaxReport": { "type": [ "object", "null" ], "properties": { "phase": { "type": "string", "enum": [ "reading", "planning", "writing", "done" ] }, "dry_run": { "type": "boolean" }, "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "company_rut": { "type": "object", "properties": { "rut": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "sii", "chipax", "none" ] } }, "required": [ "rut", "source" ], "description": "The workspace's own RUT the run writes as (issuer of its sales, receiver of its purchases) and its source: sii = the SII connection, chipax = the company Chipax's login names (no SII connection yet), none = neither (a dry run reports it; an import refuses with 409 company_rut_unknown). An SII RUT that differs from Chipax's fails the run (chipax_company_mismatch). Absent on runs from before 2026-11-02." }, "read": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Rows read from Chipax per endpoint." }, "accounts": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." }, "items": { "type": "array", "items": { "type": "object", "properties": { "chipax_account": { "type": "integer" }, "name": { "type": "string" }, "chipax_path": { "type": "string" }, "kind": { "type": "string", "enum": [ "ingreso", "costo", "gasto", "no_operacional" ] }, "action": { "type": "string", "enum": [ "map", "create", "skip" ], "description": "map = file it under an existing Vitrina account (`account_id`); create = recreate it in the plan de cuentas (same name and tree); skip = do not import what Chipax classified there." }, "account_id": { "type": [ "string", "null" ] }, "account_path": { "type": [ "string", "null" ] }, "chipax_parent_account": { "type": [ "integer", "null" ] }, "basis": { "type": "string", "enum": [ "previous_import", "chosen", "same_name", "new", "ambiguous" ], "description": "previous_import = mapped by an earlier run; chosen = the person chose it; same_name = matched to an existing Vitrina account of the same kind, by name or by the tree (`match` says how); new = will be created; ambiguous = several candidates (pick one in `account_map`)." }, "match": { "type": "string", "enum": [ "previous", "chosen", "exact", "normalized", "similar", "prefix", "children", "kept_distinct", "none", "ambiguous" ], "description": "How: exact = same name; normalized = same once case, accents, plurals, «de»/«y» and a «(…)» qualifier are folded; similar = one or two letters apart, under the account its Chipax parent maps to; prefix = one name starts the other, there too; children = its children already sit under that account; kept_distinct = another Chipax account claimed the same match, so this one is created rather than merged; none = nothing alike, created. Absent on runs before 2026-11-02." }, "reason": { "type": "string", "description": "The decision in one sentence (Spanish), for the person reviewing the dry run. Absent on runs before 2026-11-02." }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "path" ] } }, "retiros": { "type": "boolean", "description": "true = an owner-withdrawals account (name «Retiros…»): imported as non-operating onto the system «Retiros» account, shown below the resultado, never as a gasto. Absent on runs before 2026-11-08." } }, "required": [ "chipax_account", "name", "chipax_path", "kind", "action", "account_id", "account_path", "chipax_parent_account", "basis", "candidates" ] } }, "retiros": { "type": "integer", "description": "Chipax accounts named «Retiros…» filed below the resultado as non-operating (not a gasto). Absent on runs before 2026-11-08." } }, "required": [ "create", "match", "already", "skip", "skip_reasons", "items" ] }, "contrapartes": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." } }, "required": [ "create", "match", "already", "skip", "skip_reasons" ] }, "documents": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." }, "by_model": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "create", "match", "already", "skip", "skip_reasons", "by_model" ] }, "classifications": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." }, "scaled": { "type": "integer", "description": "Documents whose Chipax amounts were spread over the document total (Chipax classified the net)." }, "partial": { "type": "integer", "description": "Facturas Chipax classified only in part: Vitrina takes exactly the classified amounts and leaves the rest unclassified (it surfaces in Por resolver). Absent on runs before 2026-11-03." }, "partial_items": { "type": "array", "items": { "type": "object", "properties": { "chipax_ref": { "type": "string" }, "label": { "type": "string" }, "total_clp": { "type": "integer" }, "unclassified_clp": { "type": "integer" } }, "required": [ "chipax_ref", "label", "total_clp", "unclassified_clp" ] } } }, "required": [ "create", "match", "already", "skip", "skip_reasons", "scaled" ] }, "credit_notes": { "type": "array", "items": { "type": "object", "properties": { "chipax_ref": { "type": "string" }, "folio": { "type": [ "string", "null" ] }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "path": { "type": "string", "enum": [ "summary", "boleta_reference", "none" ] } }, "required": [ "chipax_ref", "folio", "day", "amount_clp", "path" ] }, "description": "Every nota de crédito of sales and how it got its accounts: summary = Chipax hangs it on a monthly boleta summary (it takes the summary's income accounts); boleta_reference = it references a boleta (the summary of that month); none = neither, left unclassified («Ingresos sin clasificar»). Absent on runs before 2026-11-03." }, "links": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." } }, "required": [ "create", "match", "already", "skip", "skip_reasons" ] }, "movement_classifications": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." } }, "required": [ "create", "match", "already", "skip", "skip_reasons" ] }, "rules": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." }, "items": { "type": "array", "items": { "type": "object", "properties": { "rut": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "document_kind": { "type": "string" }, "chipax_account": { "type": "integer" }, "account_id": { "type": [ "string", "null" ] }, "documents": { "type": "integer" } }, "required": [ "rut", "name", "document_kind", "chipax_account", "account_id", "documents" ] } } }, "required": [ "create", "match", "already", "skip", "skip_reasons", "items" ] }, "payment_terms": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." }, "items": { "type": "array", "items": { "type": "object", "properties": { "rut": { "type": "string" }, "days": { "type": "integer" }, "documents": { "type": "integer" }, "origin": { "type": "string", "enum": [ "chipax", "inferred" ], "description": "chipax = the supplier's own term in Chipax; inferred = from the due dates of its invoices." } }, "required": [ "rut", "days", "documents" ] } }, "defaults": { "type": "array", "items": { "type": "object", "properties": { "class": { "type": "string", "enum": [ "suppliers", "customers", "honorarios", "expenses" ] }, "days": { "type": "integer" }, "changed": { "type": "boolean", "description": "False when Vitrina already holds that number, or a person set another one (never overwritten)." } }, "required": [ "class", "days", "changed" ] }, "description": "The company's default payment terms per class, as Chipax holds them." } }, "required": [ "create", "match", "already", "skip", "skip_reasons", "items" ] }, "aliases": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." } }, "required": [ "create", "match", "already", "skip", "skip_reasons" ] }, "bank_accounts": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." }, "items": { "type": "array", "items": { "type": "object", "properties": { "chipax_account": { "type": "string", "description": "Chipax's `cuenta_corriente_id`." }, "name": { "type": "string" }, "institution": { "type": [ "string", "null" ] }, "number_tail": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "cuenta_corriente", "cuenta_vista", "tarjeta_credito", "linea_credito", "mercado_pago", "otra" ] }, "currency": { "type": [ "string", "null" ], "enum": [ "CLP", "USD" ] }, "action": { "type": "string", "enum": [ "map", "create", "skip" ], "description": "map = the Vitrina account with the same number and currency; create = a new manual account; skip = not imported (currency_unsupported)." }, "account_id": { "type": [ "string", "null" ] }, "reason": { "type": "string" } }, "required": [ "chipax_account", "name", "institution", "number_tail", "type", "currency", "action", "account_id", "reason" ] } } }, "required": [ "create", "match", "already", "skip", "skip_reasons", "items" ], "description": "Chipax's bank accounts (/cuentas-corrientes) and the Vitrina account each one is. Absent on runs before 2026-11-02." }, "movements": { "type": "object", "properties": { "create": { "type": "integer", "description": "New in Vitrina (dry run: would be created)." }, "match": { "type": "integer", "description": "Already in Vitrina (e.g. from the SII): matched and enriched." }, "already": { "type": "integer", "description": "Imported by an earlier run: nothing to do." }, "skip": { "type": "integer" }, "skip_reasons": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Why: unmapped_account, ambiguous, no_categories, voided, classified_in_vitrina (a person already classified it: kept), company_rut_unknown (connect the SII first), movement_not_found (the bank movement is not in Vitrina: connect the bank or upload the cartola), movement_ambiguous, document_not_imported, direction_mismatch, nothing_open, movement_to_income, linked_to_another_contraparte, rut_is_another_contraparte, non_positive, chosen_skip; bank movements: no_bank_account (the line names no account at all; a line Chipax books on its «no account» bucket, cuenta_corriente_id 0, lands on a manual account «Chipax: movimientos sin cuenta bancaria» since 2026-11-03), bank_account_not_imported, currency_unsupported, unreadable, ingest_failed, usd_rate_missing (no dólar observado for the day: that line alone)." } }, "required": [ "create", "match", "already", "skip", "skip_reasons" ], "description": "Chipax's statement lines (/flujo-caja/cartolas) as bank movements, source chipax: create = new rows; match = the transfer was already in Vitrina from another rail (the bank's e-mail, a feed), kept as its twin, never a second row; already = an earlier run. Absent on runs before 2026-11-02." }, "usd_movements": { "type": "object", "properties": { "lines": { "type": "integer" }, "converted": { "type": "integer" }, "failed": { "type": "integer" }, "usd_total": { "type": "integer", "description": "In cents." }, "clp_total": { "type": "integer" }, "rate_years": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "cached", "fetched", "failed" ] } }, "missing_days": { "type": "array", "items": { "type": "string" } }, "items": { "type": "array", "items": { "type": "object", "properties": { "chipax_id": { "type": "integer" }, "day": { "type": "string" }, "usd": { "type": "integer", "description": "In cents." }, "status": { "type": "string", "enum": [ "converted", "failed", "already" ] }, "rate_date": { "type": [ "string", "null" ], "description": "The day of the dólar observado used: the line's day, or the last business day before it (weekend/holiday, at most 4 days back)." }, "rate_clp": { "type": [ "number", "null" ] }, "clp": { "type": [ "integer", "null" ] } }, "required": [ "chipax_id", "day", "usd", "status", "rate_date", "rate_clp", "clp" ] }, "description": "Every USD line and the rate it used. Absent on runs before 2026-11-03." } }, "required": [ "lines", "converted", "failed", "usd_total", "clp_total", "rate_years", "missing_days" ], "description": "Chipax's USD lines (a dollar card) and their CLP at each day's dólar observado, a dry run included. Rule: the dólar observado of the line's day; a day with none published (weekend, holiday) takes the previous business day, at most 4 calendar days back; anything else fails that line alone (skip reason usd_rate_missing), never an older rate. The rate cache is filled first per year (mindicador, then the SII's yearly table). Absent when there are none, and on runs before 2026-11-03." }, "chipax_wins": { "type": "object", "properties": { "links_undone": { "type": "integer" }, "classifications_removed": { "type": "integer" }, "contrapartes_merged": { "type": "integer" } }, "required": [ "links_undone", "classifications_removed", "contrapartes_merged" ], "description": "Chipax's people win over Vitrina's automatic work: links_undone = links the matcher, a rule or the IA made that Chipax reconciles differently, undone by the system so Chipax's go in; classifications_removed = movements whose IA / rule classification was removed because Chipax reconciles them to a document (it would count twice) or classifies them itself; contrapartes_merged = Contrapartes made from payments to a RUT that Chipax says paid one supplier, merged into it (the RUT becomes its alias). A person's work is never touched. A dry run counts what the import would do. Absent on runs before 2026-11-03." }, "unmapped": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "account", "document", "link", "classification" ] }, "chipax_ref": { "type": "string" }, "label": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "type", "chipax_ref", "label", "reason" ] } }, "totals_check": { "type": "object", "properties": { "available": { "type": "boolean" }, "mismatches": { "type": "integer", "description": "Rows with a difference no reason covers." }, "explained": { "type": "integer", "description": "Rows whose whole difference has a reason. Absent on runs before 2026-11-03." }, "explained_by_code": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "The explained pesos per reason over every row. Absent on runs before 2026-11-03." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "chipax_account": { "type": "integer" }, "account_id": { "type": [ "string", "null" ] }, "month": { "type": "string" }, "chipax_clp": { "type": "integer", "description": "Chipax's Resultado Operacional for the account and month." }, "imported_chipax_clp": { "type": "integer", "description": "What Chipax classified on the documents now classified in Vitrina." }, "vitrina_clp": { "type": "integer", "description": "What Vitrina will book in that account and month for those documents, at the Resultado basis: net of IVA, a nota de crédito subtracts (runs before 2026-11-03: the lines on the document total)." }, "difference_clp": { "type": "integer", "description": "vitrina_clp − chipax_clp. Absent on runs before 2026-11-03." }, "explanations": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "boletas_sin_nota_de_venta", "nota_de_credito_de_boletas", "redondeo" ] }, "amount_clp": { "type": "integer" } }, "required": [ "code", "amount_clp" ] }, "description": "The explained part of the difference, per reason: boletas_sin_nota_de_venta (a boleta summary books the month's boletas; Chipax's RO counts only its notas de venta), nota_de_credito_de_boletas (a nota de crédito of boletas subtracts in Vitrina; Chipax's RO leaves it out), redondeo (a split line prorated to the net books at most ±1 peso off Chipax). Absent on runs before 2026-11-03." }, "unexplained_clp": { "type": "integer", "description": "The part of the difference no reason covers. Absent on runs before 2026-11-03." }, "status": { "type": "string", "enum": [ "match", "explained", "mismatch" ], "description": "match = no difference; explained = every peso of the difference has a reason; mismatch = some does not. Absent on runs before 2026-11-03." }, "matches": { "type": "boolean", "description": "No unexplained peso (status is not mismatch)." } }, "required": [ "chipax_account", "account_id", "month", "chipax_clp", "imported_chipax_clp", "vitrina_clp", "matches" ] } }, "excluded_balance_rows": { "type": "integer", "description": "Account × month rows left out of the check: balance accounts (activo, pasivo, patrimonio), which Chipax's Resultado Operacional does not cover. Absent on runs before 2026-11-02." } }, "required": [ "available", "mismatches", "rows" ] }, "not_in_api": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "phase", "dry_run", "range", "read", "accounts", "contrapartes", "documents", "classifications", "links", "movement_classifications", "rules", "payment_terms", "aliases", "unmapped", "totals_check", "not_in_api", "warnings" ], "description": "Null in lists; on GET by id, the report (partial while running)." }, "FinanzasChipaxImport": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "dry_run", "import" ] }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "account_map": { "type": "array", "items": { "type": "object", "properties": { "chipax_account": { "type": "integer" }, "action": { "type": "string", "enum": [ "map", "create", "skip" ], "description": "map = file it under an existing Vitrina account (`account_id`); create = recreate it in the plan de cuentas (same name and tree); skip = do not import what Chipax classified there." }, "account_id": { "type": [ "string", "null" ] } }, "required": [ "chipax_account", "action" ] } }, "requested_by": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "finished_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "created_at": { "type": "string", "description": "ISO 8601 timestamp." }, "report": { "$ref": "#/components/schemas/FinanzasChipaxReport" } }, "required": [ "id", "mode", "status", "from", "to", "account_map", "requested_by", "error", "started_at", "finished_at", "created_at", "report" ] }, "FinanzasChipaxStatus": { "type": "object", "properties": { "connected": { "type": "boolean" }, "app_id_preview": { "type": [ "string", "null" ], "description": "A masked hint of the App ID («abc…xyz»). The secret is never returned." }, "verified_at": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp." }, "active_import": { "$ref": "#/components/schemas/FinanzasChipaxImport" }, "last_import": { "$ref": "#/components/schemas/FinanzasChipaxImport" } }, "required": [ "connected", "app_id_preview", "verified_at", "active_import", "last_import" ] }, "FinanzasAiSettings": { "type": "object", "properties": { "auto_apply": { "type": "boolean", "description": "«Aplicar sugerencias de IA automáticamente». true (default): a confident IA answer is applied on its own, marked IA and undoable in Hecho por Vitrina. false: IA answers only become Por resolver proposals." }, "updated_at": { "type": [ "string", "null" ], "description": "When a person last changed it; null = never (default on)." }, "updated_by": { "type": [ "string", "null" ] } }, "required": [ "auto_apply", "updated_at", "updated_by" ] }, "FinanzasAiMetrics": { "type": "object", "properties": { "month": { "type": "string" }, "calls": { "type": "integer", "description": "IA calls in the month (one open item each)." }, "auto_applied": { "type": "integer", "description": "Applied on their own (IA in Hecho por Vitrina)." }, "proposed": { "type": "integer", "description": "Shown as the Por resolver proposal." }, "no_answer": { "type": "integer", "description": "No usable answer (the item stays for a person)." }, "undone": { "type": "integer", "description": "Auto-applied ones a person undid since." }, "undo_rate": { "type": [ "number", "null" ], "description": "undone / auto_applied, 0..1; null when nothing was applied." }, "input_tokens": { "type": "integer" } }, "required": [ "month", "calls", "auto_applied", "proposed", "no_answer", "undone", "undo_rate", "input_tokens" ] }, "FinanzasResultadoPostClose": { "type": [ "object", "null" ], "properties": { "closed_at": { "type": "string" }, "adjustment_count": { "type": "integer" }, "changed": { "type": "boolean" }, "result_delta_clp": { "type": "integer" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "path": { "type": [ "string", "null" ] }, "at_close_clp": { "type": "integer" }, "now_clp": { "type": "integer" }, "delta_clp": { "type": "integer" } }, "required": [ "account_id", "name", "path", "at_close_clp", "now_clp", "delta_clp" ] } } }, "required": [ "closed_at", "adjustment_count", "changed", "result_delta_clp", "accounts" ] }, "FinanzasResultadoRow": { "type": "object", "properties": { "key": { "type": "string", "description": "`ingresos`, `ingresos_sin_clasificar`, `costos`, `margen_bruto`, `gastos`, `egresos_sin_documento`, `egresos_sin_clasificar`, `resultado_operacional`, `retiros`, or `account:`." }, "type": { "type": "string", "enum": [ "section", "account", "line", "subtotal" ] }, "label": { "type": "string" }, "parent_key": { "type": [ "string", "null" ], "description": "`ingresos`, `ingresos_sin_clasificar`, `costos`, `margen_bruto`, `gastos`, `egresos_sin_documento`, `egresos_sin_clasificar`, `resultado_operacional`, `retiros`, or `account:`." }, "depth": { "type": "integer" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "ingreso", "costo", "gasto" ] }, "path": { "type": "string" }, "archived": { "type": "boolean" }, "has_children": { "type": "boolean" } }, "required": [ "id", "kind", "path", "archived", "has_children" ] }, "sign": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ -1 ] }, { "type": "number", "enum": [ 0 ] } ], "description": "+1 adds to the operating result, −1 subtracts, 0 = a subtotal or outside the result (Retiros)." }, "values": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "total": { "type": "integer" }, "counts": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "count_total": { "type": [ "integer", "null" ] }, "alert": { "type": "boolean", "description": "Show the alert badge: «Egresos sin documento» with items, «Retiros» with a withdrawal that has no document." }, "margin_pct": { "type": [ "array", "null" ], "items": { "type": [ "number", "null" ] } }, "margin_pct_total": { "type": [ "number", "null" ] }, "por_conciliar": { "type": [ "object", "null" ], "properties": { "values": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "total": { "type": "integer" }, "counts": { "type": "array", "items": { "type": "integer" } }, "count_total": { "type": "integer" } }, "required": [ "values", "total", "counts", "count_total" ], "description": "On `ingresos` only: documented income of the month not yet matched to money received, at document TOTALS (it is about money received; every other figure is net)." }, "undocumented": { "type": [ "object", "null" ], "properties": { "values": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "total": { "type": "integer" }, "counts": { "type": "array", "items": { "type": "integer" } }, "count_total": { "type": "integer" } }, "required": [ "values", "total", "counts", "count_total" ], "description": "On `retiros` only: the withdrawals with no document." }, "by_account": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "account_id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" }, "kind": { "type": "string" }, "total": { "type": "integer" } }, "required": [ "account_id", "name", "path", "kind", "total" ] } }, "drillable": { "type": "boolean" } }, "required": [ "key", "type", "label", "parent_key", "depth", "account", "sign", "values", "total", "counts", "count_total", "alert", "margin_pct", "margin_pct_total", "por_conciliar", "undocumented", "by_account", "drillable" ] }, "FinanzasResultado": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "current_month": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP" ] }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "proforma": { "type": "boolean" }, "closed": { "type": "boolean" }, "post_close": { "$ref": "#/components/schemas/FinanzasResultadoPostClose" }, "incompleto": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "enum": [ "dentist_cost_missing", "recurring_cost_missing" ] }, "message": { "type": "string", "description": "Spanish, ready for the tooltip." }, "account_name": { "type": [ "string", "null" ], "description": "The missing recurring account (`recurring_cost_missing`), else null." } }, "required": [ "reason", "message", "account_name" ], "description": "«Mes incompleto»: a closed month whose dentist cost is $0 or that misses a large recurring cost. It never counts for an average, the `equilibrio` or the `hora_sillon.base`; Resultado and Costos flag the same months. Null otherwise; a proforma month is never tagged." } }, "required": [ "month", "label", "proforma", "closed", "post_close", "incompleto" ] } }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasResultadoRow" } }, "summary": { "type": "object", "properties": { "resultado_operacional_clp": { "type": "integer" }, "ingresos_clp": { "type": "integer" }, "por_conciliar_clp": { "type": "integer" }, "egresos_sin_documento": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "count", "total_clp" ] }, "retiros_clp": { "type": "integer" }, "retiros_sin_documento": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" } }, "required": [ "count", "total_clp" ] } }, "required": [ "resultado_operacional_clp", "ingresos_clp", "por_conciliar_clp", "egresos_sin_documento", "retiros_clp", "retiros_sin_documento" ] }, "waterfall": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "ingresos", "costos", "gastos", "egresos_sin_documento", "egresos_sin_clasificar", "resultado_operacional" ] }, "label": { "type": "string" }, "amount_clp": { "type": "integer" }, "running_clp": { "type": "integer" } }, "required": [ "key", "label", "amount_clp", "running_clp" ] } } }, "required": [ "from", "to", "current_month", "currency", "months", "rows", "summary", "waterfall" ] }, "FinanzasResultadoItems": { "type": "object", "properties": { "row": { "type": "string" }, "account": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "total": { "type": "integer" }, "sum_clp": { "type": "integer", "description": "Equals the cell (net)." }, "gross_sum_clp": { "type": "integer", "description": "The same items at document totals." }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "movement" ] }, "id": { "type": "string" }, "day": { "type": "string" }, "periods": { "type": "array", "items": { "type": "string" } }, "amount_clp": { "type": "integer", "description": "Signed NET contribution of this item to the line (what the cell sums; por_conciliar: what it still waits for, at totals)." }, "gross_amount_clp": { "type": "integer", "description": "The same contribution at document totals (classification lines as stored)." }, "counterparty_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "account_ids": { "type": "array", "items": { "type": "string" } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string" } }, "required": [ "id", "name", "path" ] } }, "documented": { "type": "boolean" }, "accepted_without_document": { "type": "boolean" }, "document": { "type": [ "object", "null" ], "properties": { "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "total_clp": { "type": "integer" }, "result_clp": { "type": "integer", "description": "What the whole document counts for in the resultado: neto + exento (sales), total minus the recoverable IVA and specific taxes (purchases with crédito fiscal, so IVA no recuperable counts), the total otherwise." }, "payment_state": { "type": "string" } }, "required": [ "kind", "dte_type", "folio", "total_clp", "result_clp", "payment_state" ] }, "movement": { "type": [ "object", "null" ], "properties": { "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "amount_clp": { "type": "integer" } }, "required": [ "direction", "amount_clp" ] } }, "required": [ "type", "id", "day", "periods", "amount_clp", "gross_amount_clp", "counterparty_name", "description", "account_ids", "accounts", "documented", "accepted_without_document", "document", "movement" ] } } }, "required": [ "row", "account", "from", "to", "total", "sum_clp", "gross_sum_clp", "items" ] }, "FinanzasCashFlowItem": { "type": [ "object", "null" ], "properties": { "key": { "type": "string", "description": "Stable item key: document:, recurring::, retention:, rescue:, cuotas:, appointments:, cash_pending." }, "source": { "type": "string", "enum": [ "payable", "receivable", "retention", "recurring", "cuotas", "appointments", "cash_pending", "card_settlement", "rescue" ], "description": "payable = a purchase, honorario or gasto by due date; receivable = a sale or issued honorario by due date; retention = the retención of honorarios received, due with the F29; recurring = a recurring item occurrence; cuotas = patient cuotas of the day; appointments = booked appointments with a price of the day; cash_pending = efectivo por depositar (the one shared amount, `cash_pending`), spread over its expected deposit days (the next 5 business days), never all on today; card_settlement = card payments a processor has not paid out yet, on their payout day (2 business days, Chile holidays skipped); a transfer with no bank match is not projected (it is a Por resolver case); rescue = a planned «Rescatar fondo»." }, "direction": { "type": "string", "enum": [ "inflow", "outflow" ] }, "label": { "type": "string" }, "amount_clp": { "type": "integer" }, "date": { "type": "string", "description": "Where the plan puts it." }, "due_date": { "type": "string", "description": "Where its source puts it (due date, occurrence)." }, "overdue": { "type": "boolean", "description": "An overdue payable. In the plan only when moved to a date; otherwise it is a «Vencida sin pago visto» (GET /finanzas/cash-flow/overdue-no-payment-seen)." }, "movable": { "type": "boolean", "description": "«Mover pagos» applies (documents, recurring items, retención)." }, "move": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "original_on": { "type": "string" }, "note": { "type": [ "string", "null" ] } }, "required": [ "id", "original_on", "note" ] }, "document": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "dte_type", "folio" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "recurring_item_id": { "type": [ "string", "null" ] }, "rescue_id": { "type": [ "string", "null" ] }, "count": { "type": [ "integer", "null" ], "description": "How many it groups (cuotas, appointments, honorarios)." } }, "required": [ "key", "source", "direction", "label", "amount_clp", "date", "due_date", "overdue", "movable", "move", "document", "contraparte", "recurring_item_id", "rescue_id", "count" ], "description": "What «deja el saldo en …» names: the payment at which the confirmed balance first goes below zero; when it never does (or already starts below zero), the biggest payment of the lowest day." }, "FinanzasCashFlowLowest": { "type": [ "object", "null" ], "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer" }, "negative": { "type": "boolean" }, "is_today": { "type": "boolean", "description": "True when the lowest point is today (today's real balance, or a projected today lower than it): the screen says «Hoy es el punto más bajo». The balance is never above «Caja hoy»." }, "cause": { "$ref": "#/components/schemas/FinanzasCashFlowItem" }, "cause_balance_after_clp": { "type": [ "integer", "null" ], "description": "The confirmed balance right after `cause` (null without a cause)." } }, "required": [ "date", "balance_clp", "negative", "is_today", "cause", "cause_balance_after_clp" ], "description": "The lowest projected balance in the range." }, "FinanzasCashFlowOverdueNoPaymentSeen": { "type": "object", "properties": { "count": { "type": "integer" }, "amount_clp": { "type": "integer", "description": "What is still open on them (total − retención − links)." } }, "required": [ "count", "amount_clp" ], "description": "«Vencidas sin pago visto»: payables past their due date with no matching payment in the data and no date given with «Mover pagos». Vitrina does not claim they are unpaid, so they stay out of the projection and every headline. Review them with GET /finanzas/cash-flow/overdue-no-payment-seen." }, "FinanzasInheritedOverdue": { "type": "object", "properties": { "count": { "type": "integer" }, "amount_clp": { "type": "integer", "description": "Retired (Finanzas 50): always zero." } }, "required": [ "count", "amount_clp" ], "description": "Retired (Finanzas 50): always zero. The payables it counted («Vencido heredado») are «Pagado antes de Vitrina» now, settled; list them with GET /finanzas/documents?paid_before_vitrina=true.", "deprecated": true }, "FinanzasCashFlowRescue": { "type": "object", "properties": { "id": { "type": "string" }, "planned_on": { "type": "string" }, "amount_clp": { "type": "integer" }, "source_name": { "type": "string" }, "source_bank_account_id": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "planned_on", "amount_clp", "source_name", "source_bank_account_id", "note", "created_at" ] }, "FinanzasCashFlow": { "type": "object", "properties": { "as_of": { "type": "string", "description": "Today (America/Santiago)." }, "from": { "type": "string" }, "to": { "type": "string" }, "granularity": { "type": "string", "enum": [ "day", "week" ] }, "opening": { "type": "object", "properties": { "balance_clp": { "type": "integer", "description": "Today's balance of the operating accounts (every account except savings accounts)." }, "as_of": { "type": [ "string", "null" ] }, "accounts_count": { "type": "integer" }, "unknown_count": { "type": "integer", "description": "Accounts without a known balance (left out)." }, "savings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "institution_name": { "type": [ "string", "null" ] }, "balance_clp": { "type": [ "integer", "null" ] } }, "required": [ "id", "name", "institution_name", "balance_clp" ] } }, "savings_clp": { "type": "integer" } }, "required": [ "balance_clp", "as_of", "accounts_count", "unknown_count", "savings", "savings_clp" ] }, "periods": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" }, "kind": { "type": "string", "enum": [ "actual", "projected", "mixed" ] }, "inflow_clp": { "type": "integer", "description": "Actual: bank income. Projected: known income." }, "typical_inflow_clp": { "type": "integer", "description": "Projected: typical weekday income above the known income." }, "outflow_clp": { "type": "integer" }, "closing_balance_clp": { "type": "integer", "description": "The confirmed balance: bank balances plus known items only." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income (median of the last 90 days) of every projected day so far: the dashed line. Never a headline. Actual days: the real balance." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. The dashed line is `expected_balance_clp`." }, "items_count": { "type": "integer" } }, "required": [ "start", "end", "kind", "inflow_clp", "typical_inflow_clp", "outflow_clp", "closing_balance_clp", "expected_balance_clp", "band", "items_count" ] } }, "lowest": { "$ref": "#/components/schemas/FinanzasCashFlowLowest" }, "month_end": { "type": "object", "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer", "description": "The confirmed balance." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income (median of the last 90 days) of every projected day so far: the dashed line. Never a headline. Actual days: the real balance." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. The dashed line is `expected_balance_clp`." } }, "required": [ "date", "balance_clp", "expected_balance_clp", "band" ], "description": "The projected balance at the end of the current month." }, "totals": { "type": "object", "properties": { "actual_inflow_clp": { "type": "integer" }, "actual_outflow_clp": { "type": "integer" }, "projected_inflow_clp": { "type": "integer" }, "typical_inflow_clp": { "type": "integer" }, "projected_outflow_clp": { "type": "integer" }, "by_source": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "actual_inflow_clp", "actual_outflow_clp", "projected_inflow_clp", "typical_inflow_clp", "projected_outflow_clp", "by_source" ] }, "overdue": { "type": "object", "properties": { "payables_clp": { "type": "integer", "description": "Payables overdue up to 90 days with no payment seen: out of the projection (part of `overdue_no_payment_seen`)." }, "payables_count": { "type": "integer" }, "stale_payables_clp": { "type": "integer" }, "stale_payables_count": { "type": "integer" }, "receivables_clp": { "type": "integer" }, "receivables_count": { "type": "integer" } }, "required": [ "payables_clp", "payables_count", "stale_payables_clp", "stale_payables_count", "receivables_clp", "receivables_count" ] }, "overdue_no_payment_seen": { "$ref": "#/components/schemas/FinanzasCashFlowOverdueNoPaymentSeen" }, "inherited_overdue": { "$ref": "#/components/schemas/FinanzasInheritedOverdue" }, "cash_pending": { "$ref": "#/components/schemas/FinanzasCashPendingSummary" }, "typical_income": { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "history", "insufficient_history" ] }, "weeks": { "type": "integer", "description": "Whole weeks of bank history behind the weekday band." } }, "required": [ "basis", "weeks" ], "description": "What the typical weekday income stands on. `insufficient_history` = fewer than 4 weeks of bank history: no typical income is projected (every `typical_inflow_clp` is 0 and there is no band) and the page should say so." }, "band_basis": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": "string" }, "weekdays": { "type": "array", "items": { "type": [ "object", "null" ], "properties": { "weekday": { "type": "integer", "description": "0 = domingo." }, "min_clp": { "type": "integer" }, "median_clp": { "type": "integer" }, "max_clp": { "type": "integer" } }, "required": [ "weekday", "min_clp", "median_clp", "max_clp" ] } } }, "required": [ "from", "to", "weekdays" ] }, "rescues": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasCashFlowRescue" } }, "moves_count": { "type": "integer" } }, "required": [ "as_of", "from", "to", "granularity", "opening", "periods", "lowest", "month_end", "totals", "overdue", "overdue_no_payment_seen", "inherited_overdue", "cash_pending", "typical_income", "band_basis", "rescues", "moves_count" ] }, "FinanzasCashFlowCalendar": { "type": "object", "properties": { "as_of": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "opening_balance_clp": { "type": "integer" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "opening_balance_clp": { "type": "integer" }, "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashFlowItem" }, { "type": "object", "properties": { "balance_after_clp": { "type": "integer", "description": "The expected balance right after this item." } }, "required": [ "balance_after_clp" ] } ] } }, "typical_inflow_clp": { "type": "integer" }, "closing_balance_clp": { "type": "integer" } }, "required": [ "date", "opening_balance_clp", "items", "typical_inflow_clp", "closing_balance_clp" ] } }, "lowest": { "$ref": "#/components/schemas/FinanzasCashFlowLowest" } }, "required": [ "as_of", "from", "to", "opening_balance_clp", "days", "lowest" ] }, "FinanzasCashFlowMove": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Empty on a dry run." }, "item_key": { "type": "string" }, "original_on": { "type": "string" }, "planned_on": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "updated_at": { "type": "string" } }, "required": [ "id", "item_key", "original_on", "planned_on", "note", "updated_at" ], "description": "Null when the item went back to its own date." }, "FinanzasCashFlowEffect": { "type": "object", "properties": { "before": { "type": "object", "properties": { "lowest": { "$ref": "#/components/schemas/FinanzasCashFlowLowest" }, "month_end": { "type": "object", "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer", "description": "The confirmed balance." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income (median of the last 90 days) of every projected day so far: the dashed line. Never a headline. Actual days: the real balance." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. The dashed line is `expected_balance_clp`." } }, "required": [ "date", "balance_clp", "expected_balance_clp", "band" ] } }, "required": [ "lowest", "month_end" ] }, "after": { "type": "object", "properties": { "lowest": { "$ref": "#/components/schemas/FinanzasCashFlowLowest" }, "month_end": { "type": "object", "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer", "description": "The confirmed balance." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income (median of the last 90 days) of every projected day so far: the dashed line. Never a headline. Actual days: the real balance." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. The dashed line is `expected_balance_clp`." } }, "required": [ "date", "balance_clp", "expected_balance_clp", "band" ] } }, "required": [ "lowest", "month_end" ] }, "horizon": { "type": "object", "properties": { "days": { "type": "integer" }, "to": { "type": "string", "description": "Last day of the window." } }, "required": [ "days", "to" ], "description": "`lowest` is measured over today .. `to` (`horizon_days`, default 30: the page's window); `month_end` is the end of the current month." } }, "required": [ "before", "after", "horizon" ] }, "FinanzasCashFlowMoveResult": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "move": { "$ref": "#/components/schemas/FinanzasCashFlowMove" }, "item": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "amount_clp": { "type": "integer" }, "due_date": { "type": "string" }, "planned_on": { "type": "string" } }, "required": [ "key", "label", "amount_clp", "due_date", "planned_on" ] }, "effect": { "$ref": "#/components/schemas/FinanzasCashFlowEffect" } }, "required": [ "dry_run", "move", "item", "effect" ] }, "FinanzasCashFlowMoveBody": { "type": "object", "properties": { "item_key": { "type": "string", "minLength": 1, "maxLength": 120, "description": "The `key` of a movable item (document:, recurring::, retention:)." }, "planned_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The new planned day, today to a year ahead. Its own date = back to it." }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "item_key", "planned_on" ] }, "FinanzasCashFlowMoveRemoved": { "type": "object", "properties": { "removed": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashFlowMove" }, { "type": "object" } ] }, "effect": { "$ref": "#/components/schemas/FinanzasCashFlowEffect" } }, "required": [ "removed", "effect" ] }, "FinanzasCashFlowRescueResult": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "rescue": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashFlowRescue" }, { "type": [ "object", "null" ], "description": "Null on a dry run." } ] }, "effect": { "$ref": "#/components/schemas/FinanzasCashFlowEffect" } }, "required": [ "dry_run", "rescue", "effect" ] }, "FinanzasCashFlowRescueBody": { "type": "object", "properties": { "planned_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Today to a year ahead." }, "amount_clp": { "type": "integer", "minimum": 1, "maximum": 100000000000 }, "source_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 120, "description": "What it comes from («Fondo mutuo Itaú»). Defaults to the account name." }, "source_bank_account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "A savings account (cuenta de ahorro) it comes from." }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "planned_on", "amount_clp" ] }, "FinanzasCashFlowRescueRemoved": { "type": "object", "properties": { "removed": { "$ref": "#/components/schemas/FinanzasCashFlowRescue" } }, "required": [ "removed" ] }, "FinanzasRecurringItem": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "amount_clp": { "type": "integer" }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly", "yearly" ], "description": "weekly = every 7 days; biweekly = every 14 days (quincenal); monthly, quarterly and yearly keep the day of the month of `starts_on` (clamped to the month's last day)." }, "starts_on": { "type": "string" }, "ends_on": { "type": [ "string", "null" ] }, "account": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" }, "archived": { "type": "boolean" } }, "required": [ "id", "name", "kind", "archived" ] }, "contraparte": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "note": { "type": [ "string", "null" ] }, "summary": { "type": "string", "description": "«Mensual · $2.847.000»." }, "status": { "type": "string", "enum": [ "active", "scheduled", "ended" ] }, "next_on": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "direction", "amount_clp", "cadence", "starts_on", "ends_on", "account", "contraparte", "note", "summary", "status", "next_on", "created_at", "updated_at" ] }, "FinanzasRecurringItemBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "amount_clp": { "type": "integer", "minimum": 1, "maximum": 100000000000 }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly", "yearly" ], "description": "weekly = every 7 days; biweekly = every 14 days (quincenal); monthly, quarterly and yearly keep the day of the month of `starts_on` (clamped to the month's last day)." }, "starts_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "ends_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "account_id": { "type": "string", "format": "uuid", "description": "The plan de cuentas account (Arriendo, Sueldos…)." }, "contraparte_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional: a document of this Contraparte due near an occurrence stands for it (never counted twice)." }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "name", "direction", "amount_clp", "cadence", "starts_on", "account_id" ] }, "FinanzasRecurringItemPatch": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "direction": { "type": "string", "enum": [ "outflow", "inflow" ] }, "amount_clp": { "type": "integer", "minimum": 1, "maximum": 100000000000 }, "cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly", "yearly" ], "description": "weekly = every 7 days; biweekly = every 14 days (quincenal); monthly, quarterly and yearly keep the day of the month of `starts_on` (clamped to the month's last day)." }, "starts_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "ends_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "account_id": { "type": "string", "format": "uuid", "description": "The plan de cuentas account (Arriendo, Sueldos…)." }, "contraparte_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional: a document of this Contraparte due near an occurrence stands for it (never counted twice)." }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "additionalProperties": false }, "FinanzasRecurringItemEndBody": { "type": "object", "properties": { "ends_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The last day an occurrence may fall on. Default: today (the day before it starts, if it has not started)." } } }, "FinanzasCashFlowOverdueNoPaymentSeenList": { "type": "object", "properties": { "as_of": { "type": "string" }, "count": { "type": "integer" }, "amount_clp": { "type": "integer" }, "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashFlowItem" }, { "type": "object" } ] }, "description": "Newest due date first. `date` = `due_date`; each is movable («Mover pagos» puts it back in the plan on that day)." } }, "required": [ "as_of", "count", "amount_clp", "items" ] }, "FinanzasCashFlowOverdueResolveResult": { "type": "object", "properties": { "batch_id": { "type": "string", "format": "uuid", "description": "Pass it to POST /finanzas/inherited-overdue/batches/{batchId}/undo («Deshacer»)." }, "resolved": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reason": { "type": "string", "enum": [ "not_found", "not_eligible" ], "description": "not_eligible: not an overdue open payable any more (paid, linked, voided, or someone got there first)." } }, "required": [ "id", "reason" ] } }, "amount_clp": { "type": "integer", "description": "What was open on the documents marked paid." }, "remaining": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashFlowOverdueNoPaymentSeen" }, { "description": "The «Vencidas sin pago visto» left after this batch." } ] } }, "required": [ "batch_id", "resolved", "skipped", "amount_clp", "remaining" ] }, "FinanzasCashFlowOverdueResolveBody": { "type": "object", "properties": { "document_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500 }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "document_ids" ] }, "FinanzasAlert": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "cash_negative", "f29_due", "supplier_invoice_missing" ], "description": "`cash_negative`: the Flujo de caja projection drops below zero in the next 30 days. `f29_due`: an F29 with something to pay is due within 5 days and is unpaid. `supplier_invoice_missing`: a Contraparte that invoiced each of the last 3 months has no invoice this month, 3 days past its usual day." }, "title": { "type": "string", "description": "One line, Spanish." }, "body": { "type": "string", "description": "What happened and what to do." }, "cta_label": { "type": "string", "description": "The button that fixes it." }, "path": { "type": "string", "description": "Workspace-relative screen that fixes it (`/finanzas/reportes/flujo-de-caja`, `/finanzas/documentos?vista=f29`, `/finanzas/contrapartes/`)." }, "opened_on": { "type": "string", "description": "Day first seen (YYYY-MM-DD, Santiago)." }, "notified_at": { "type": [ "string", "null" ], "description": "When the members were told; null until then." }, "updated_at": { "type": "string" }, "data": { "type": "object", "additionalProperties": {}, "description": "The facts, whole CLP. cash_negative: `lowest_date`, `lowest_balance_clp`, `today_balance_clp`, `cause_label`, `cause_amount_clp`, `horizon_days`. f29_due: `period`, `due_date`, `amount_clp`, `days_left`, `amount_is_final`, `document_id`. supplier_invoice_missing: `contraparte_id`, `contraparte_name`, `period`, `usual_day`, `typical_amount_clp`, `months_invoiced`." } }, "required": [ "id", "kind", "title", "body", "cta_label", "path", "opened_on", "notified_at", "updated_at", "data" ] }, "FinanzasAlertList": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasAlert" } }, "FinanzasMandatoSignature": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "phase": { "type": "string", "enum": [ "none", "pending_signature", "connecting", "connected", "failed", "declined", "revoked" ], "description": "`pending_signature` = the representante legal has the link; `connecting` = signed, being registered at the SII («Firmado, conectando con el SII…»); `connected` = registered; `failed` = signed but the SII registration keeps failing (retried automatically); `declined` = the signer rejected; `revoked` = revoked in Bancos y SII." }, "status": { "type": "string" }, "terms_version": { "type": "string" }, "terms_sha256": { "type": "string" }, "signer": { "type": "object", "properties": { "name": { "type": "string" }, "rut": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "rut", "email" ] }, "signing_url": { "type": [ "string", "null" ], "description": "The representante legal's signing link while the signature is pending; null afterwards." }, "signed_at": { "type": [ "string", "null" ] }, "attested_at": { "type": [ "string", "null" ] }, "problem": { "type": [ "string", "null" ] }, "document_available": { "type": "boolean", "description": "The signed PDF can be downloaded (`GET …/sii/{id}/mandato/document`)." }, "created_at": { "type": "string" } }, "required": [ "id", "phase", "status", "terms_version", "terms_sha256", "signer", "signing_url", "signed_at", "attested_at", "problem", "document_available", "created_at" ] }, "FinanzasDigestPreview": { "type": "object", "properties": { "week_start": { "type": "string", "description": "Monday of this week (YYYY-MM-DD, workspace time)." }, "send_at": { "type": "string", "description": "This week's send moment: Monday 09:00 workspace time (ISO)." }, "next_send_at": { "type": "string", "description": "Next Monday's 09:00 workspace time (ISO)." }, "status": { "type": "string", "enum": [ "pending", "sent", "empty", "missed" ], "description": "This week's digest: `pending` (Monday's send window has not closed and nothing went out yet), `sent`, `empty` (no finance data, nothing went out) or `missed` (the window closed without a digest: the workspace had data but it did not go, e.g. it joined mid-week or the send failed; the next one is `next_send_at`)." }, "sent_at": { "type": [ "string", "null" ] }, "will_send": { "type": "boolean", "description": "The workspace has finance data now; false = no digest would go out." }, "channels": { "type": "object", "properties": { "email": { "type": "boolean" }, "whatsapp": { "type": "boolean" } }, "required": [ "email", "whatsapp" ], "description": "The caller's own channels: their notification preferences for `finanzas.weekly_digest` and, for WhatsApp, the admin's opt-in `finanzas_whatsapp` rail with an approved digest template." }, "email": { "type": "object", "properties": { "subject": { "type": "string" }, "hero": { "type": "object", "properties": { "label": { "type": "string", "description": "«Caja hoy» or «Te necesita»." }, "value": { "type": "string", "description": "THE big number, formatted." }, "caption": { "type": [ "string", "null" ] } }, "required": [ "label", "value", "caption" ] }, "problem": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "link": { "type": "object", "properties": { "label": { "type": "string" }, "path": { "type": "string", "description": "Workspace-relative screen (prefix `/w/`)." } }, "required": [ "label", "path" ] } }, "required": [ "text", "link" ], "description": "The one problem (the only red line): the cash runs out within 30 days, or a bank needs reconnecting. Null when there is none." }, "lines": { "type": "array", "items": { "type": "string" }, "description": "The rest: the month against the punto de equilibrio, the open cases, what Vitrina ordered." }, "overdue_unpaid": { "type": [ "object", "null" ], "properties": { "text": { "type": "string" }, "link": { "type": "object", "properties": { "label": { "type": "string" }, "path": { "type": "string", "description": "Workspace-relative screen (prefix `/w/`)." } }, "required": [ "label", "path" ] } }, "required": [ "text", "link" ], "description": "«$X en facturas vencidas sin pago visto» with a link to review them; they are not in the cash forecast. Null when there are none or the caller cannot read reports." }, "primary": { "type": "object", "properties": { "label": { "type": "string" }, "path": { "type": "string", "description": "Workspace-relative screen (prefix `/w/`)." } }, "required": [ "label", "path" ] }, "secondary": { "type": "object", "properties": { "label": { "type": "string" }, "path": { "type": "string", "description": "Workspace-relative screen (prefix `/w/`)." } }, "required": [ "label", "path" ] } }, "required": [ "subject", "hero", "problem", "lines", "overdue_unpaid", "primary", "secondary" ] }, "whatsapp_text": { "type": "string", "description": "The WhatsApp `{{resumen}}` for the caller." }, "figures": { "type": "object", "properties": { "reports_visible": { "type": "boolean" }, "cash_today_clp": { "type": [ "integer", "null" ] }, "month_end_clp": { "type": [ "integer", "null" ] }, "in_30_days_clp": { "type": [ "integer", "null" ] }, "runs_out_date": { "type": [ "string", "null" ] }, "ingresos_clp": { "type": [ "integer", "null" ] }, "resultado_clp": { "type": [ "integer", "null" ] }, "equilibrio_clp": { "type": [ "integer", "null" ] }, "open_cases": { "type": "integer" } }, "required": [ "reports_visible", "cash_today_clp", "month_end_clp", "in_30_days_clp", "runs_out_date", "ingresos_clp", "resultado_clp", "equilibrio_clp", "open_cases" ], "description": "The same figures as `GET /finanzas/resumen` (whole CLP). Cash and result are null without `finanzas_reports:read`." } }, "required": [ "week_start", "send_at", "next_send_at", "status", "sent_at", "will_send", "channels", "email", "whatsapp_text", "figures" ] }, "FinanzasEquilibrioProduccion": { "type": [ "object", "null" ], "properties": { "equilibrio_clp": { "type": "integer", "description": "The average break-even converted to production terms: `equilibrio.equilibrio_clp` × `ratio`." }, "ratio": { "type": "number", "description": "Producción ÷ ventas netas over `months` (sums, not a mean of ratios), three decimals." }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "ingresos_clp": { "type": "integer" }, "produccion_clp": { "type": "integer" } }, "required": [ "month", "label", "ingresos_clp", "produccion_clp" ] }, "description": "The bar months that have both figures, oldest first (at most 3)." } }, "required": [ "equilibrio_clp", "ratio", "months" ] }, "FinanzasCostos": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "current_month": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP" ] }, "is_clinic": { "type": "boolean", "description": "Clinic workspaces get `dentist_share` and `hora_sillon`; others see break-even only (both null)." }, "reference_month": { "type": [ "string", "null" ], "description": "The last month of the range that is not proforma (the headline), or null." }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "proforma": { "type": "boolean" }, "incompleto": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string", "enum": [ "dentist_cost_missing", "recurring_cost_missing" ] }, "message": { "type": "string", "description": "Spanish, ready for the tooltip." }, "account_name": { "type": [ "string", "null" ], "description": "The missing recurring account (`recurring_cost_missing`), else null." } }, "required": [ "reason", "message", "account_name" ], "description": "«Mes incompleto»: a closed month whose dentist cost is $0 or that misses a large recurring cost. It never counts for an average, the `equilibrio` or the `hora_sillon.base`; Resultado and Costos flag the same months. Null otherwise; a proforma month is never tagged." }, "fijos_faltantes_clp": { "type": "integer", "description": "Recurring fixed costs not booked yet in this closed month, at their usual amount (the sum of `fijos_faltantes`). Already inside `equilibrio_clp`; never inside `fijos_clp` or `resultado_clp`. 0 on a proforma month." }, "fijos_faltantes": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" }, "usual_clp": { "type": "integer", "description": "Median of the account’s last 3 non-zero months before the gap." } }, "required": [ "account_id", "account_name", "usual_clp" ] }, "description": "The accounts behind `fijos_faltantes_clp`, usual amount descending." }, "ingresos_clp": { "type": "integer", "description": "The Resultado’s «Ingresos» (net)." }, "variables_clp": { "type": "integer", "description": "Costs on accounts flagged variable (documented or not) + «Egresos sin clasificar»." }, "sin_clasificar_clp": { "type": "integer", "description": "Part of `variables_clp` that is «Egresos sin clasificar»." }, "fijos_clp": { "type": "integer", "description": "Costs on accounts flagged fijo." }, "contribucion_clp": { "type": "integer", "description": "ingresos − variables." }, "contribucion_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal." }, "equilibrio_clp": { "type": [ "integer", "null" ], "description": "Punto de equilibrio: (fijos + fijos faltantes) ÷ margen de contribución %, the monthly income at which the result is zero. `fijos_clp` stays the books; the recurring fixed costs not booked yet enter here at their usual amount (month rows: `fijos_faltantes_clp`). Null when it cannot be reached (see `equilibrio_sin_calculo`)." }, "equilibrio_sin_calculo": { "type": [ "string", "null" ], "enum": [ "sin_ingresos", "margen_no_positivo" ] }, "brecha_clp": { "type": [ "integer", "null" ], "description": "ingresos − equilibrio (positive: above break-even)." }, "cobertura_pct": { "type": [ "number", "null" ], "description": "ingresos ÷ equilibrio, one decimal." }, "resultado_clp": { "type": "integer", "description": "ingresos − variables − fijos = the Resultado operacional." } }, "required": [ "month", "label", "proforma", "incompleto", "fijos_faltantes_clp", "fijos_faltantes", "ingresos_clp", "variables_clp", "sin_clasificar_clp", "fijos_clp", "contribucion_clp", "contribucion_pct", "equilibrio_clp", "equilibrio_sin_calculo", "brecha_clp", "cobertura_pct", "resultado_clp" ] } }, "equilibrio": { "type": [ "object", "null" ], "properties": { "equilibrio_clp": { "type": "integer", "description": "The average break-even of the last 3 complete months, «Mes incompleto» skipped." }, "from": { "type": "string" }, "to": { "type": "string" }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "equilibrio_clp": { "type": "integer" } }, "required": [ "month", "label", "equilibrio_clp" ] } }, "fijos_faltantes_clp": { "type": "integer", "description": "Mean of the bar months’ `fijos_faltantes_clp`; already inside `equilibrio_clp`." }, "fijos_faltantes_accounts": { "type": "array", "items": { "type": "string" }, "description": "Distinct names of the accounts missing in any bar month, usual amount descending." } }, "required": [ "equilibrio_clp", "from", "to", "months", "fijos_faltantes_clp", "fijos_faltantes_accounts" ], "description": "The bar the current month is judged against; independent of the range asked for. Null when no complete month has a break-even." }, "equilibrio_produccion": { "$ref": "#/components/schemas/FinanzasEquilibrioProduccion" }, "period": { "type": "object", "properties": { "ingresos_clp": { "type": "integer", "description": "The Resultado’s «Ingresos» (net)." }, "variables_clp": { "type": "integer", "description": "Costs on accounts flagged variable (documented or not) + «Egresos sin clasificar»." }, "sin_clasificar_clp": { "type": "integer", "description": "Part of `variables_clp` that is «Egresos sin clasificar»." }, "fijos_clp": { "type": "integer", "description": "Costs on accounts flagged fijo." }, "contribucion_clp": { "type": "integer", "description": "ingresos − variables." }, "contribucion_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal." }, "equilibrio_clp": { "type": [ "integer", "null" ], "description": "Punto de equilibrio: (fijos + fijos faltantes) ÷ margen de contribución %, the monthly income at which the result is zero. `fijos_clp` stays the books; the recurring fixed costs not booked yet enter here at their usual amount (month rows: `fijos_faltantes_clp`). Null when it cannot be reached (see `equilibrio_sin_calculo`)." }, "equilibrio_sin_calculo": { "type": [ "string", "null" ], "enum": [ "sin_ingresos", "margen_no_positivo" ] }, "brecha_clp": { "type": [ "integer", "null" ], "description": "ingresos − equilibrio (positive: above break-even)." }, "cobertura_pct": { "type": [ "number", "null" ], "description": "ingresos ÷ equilibrio, one decimal." }, "resultado_clp": { "type": "integer", "description": "ingresos − variables − fijos = the Resultado operacional." }, "months": { "type": "integer" } }, "required": [ "ingresos_clp", "variables_clp", "sin_clasificar_clp", "fijos_clp", "contribucion_clp", "contribucion_pct", "equilibrio_clp", "equilibrio_sin_calculo", "brecha_clp", "cobertura_pct", "resultado_clp", "months" ], "description": "Monthly averages over the range; equilibrio = average fijos ÷ the range’s margin %." }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "path": { "type": "string" }, "kind": { "type": "string", "enum": [ "costo", "gasto" ] }, "behavior": { "type": "string", "enum": [ "fijo", "variable" ] }, "behavior_inherited": { "type": "boolean" }, "usual_monthly_clp": { "type": [ "integer", "null" ], "description": "Fijo accounts: median of the last 3 non-zero closed months within 12 months before the current one. Null for variable accounts or when never seen." }, "recurring": { "type": "boolean", "description": "The recurring (non-zero in 3 of the 6 months up to its last booking) and stable (last amount within 25 % of the usual) test holds." }, "missing_since": { "type": [ "string", "null" ], "description": "`YYYY-MM`: the account is missing in the last closed month; the first month of that run of zeros. Null otherwise." }, "values": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "total_clp": { "type": "integer" } }, "required": [ "account_id", "name", "path", "kind", "behavior", "behavior_inherited", "usual_monthly_clp", "recurring", "missing_since", "values", "total_clp" ] } }, "dentist_share": { "type": [ "object", "null" ], "properties": { "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "source": { "type": "string", "enum": [ "settings", "detected", "none" ] }, "values": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "total_clp": { "type": "integer" }, "pct": { "type": "array", "items": { "type": [ "number", "null" ] } }, "pct_total": { "type": [ "number", "null" ], "description": "Percent, one decimal." }, "reference": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "share_bps": { "type": "integer" }, "label": { "type": "string" }, "values": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "total_clp": { "type": [ "integer", "null" ] } }, "required": [ "enabled", "share_bps", "label", "values", "total_clp" ] } }, "required": [ "account_ids", "source", "values", "total_clp", "pct", "pct_total", "reference" ], "description": "The treating dentist’s share (a variable cost, already inside `variables_clp`) and the optional reference line («Un tercio de la venta» by default). Clinics only." }, "hora_sillon": { "type": [ "object", "null" ], "properties": { "base": { "type": [ "object", "null" ], "properties": { "months": { "type": "array", "items": { "type": "string" }, "description": "The months behind the headline cost per hour, oldest first: the same last 3 complete months as `equilibrio`." }, "fijos_clp": { "type": "integer", "description": "Mean fijos of those months." }, "fijos_faltantes_clp": { "type": "integer", "description": "Mean «fijos que aún no aparecen» of those months (also inside `equilibrio`)." }, "available_hours": { "type": "number", "description": "Mean available chair-hours of those months." }, "costo_hora_clp": { "type": [ "integer", "null" ], "description": "(fijos + fijos faltantes) ÷ available hours: the headline «Costo hora sillón». Null with no hours." }, "occupancy_month": { "type": [ "string", "null" ], "description": "The last complete month of the range: occupancy and attended hours are read from it. Null when the range has none." } }, "required": [ "months", "fijos_clp", "fijos_faltantes_clp", "available_hours", "costo_hora_clp", "occupancy_month" ], "description": "Base of the headline cost per hour (D12). Null when there is no complete month." }, "chairs": { "type": "integer", "description": "Total chairs counted (same as `chairs_source.count`)." }, "chairs_source": { "type": "object", "properties": { "count": { "type": "integer" }, "source": { "type": "string", "enum": [ "resources", "override", "none" ], "description": "`resources`: the clinic’s active boxes/sillones (native or mirrored from its previous system); `override`: the owner’s count; `none`: no chairs known (ask «¿Cuántos sillones tienes?»)." }, "source_label": { "type": [ "string", "null" ], "description": "User-facing origin: «de tu agenda», «de Dentalink», «de Medilink», «elegido por ti»; null when `source` is `none`." } }, "required": [ "count", "source", "source_label" ], "description": "Where the chair count comes from." }, "lunch_break_minutes": { "type": "integer", "description": "Weekday (Mon–Fri) lunch break already subtracted from `available_hours` on days open 6 h or more." }, "available_hours": { "type": "array", "items": { "type": "number" }, "description": "Hours per entry of `months`, one decimal." }, "attended_hours": { "type": "array", "items": { "type": "number" }, "description": "Hours per entry of `months`, one decimal." }, "available_hours_total": { "type": "number" }, "attended_hours_total": { "type": "number" }, "production_clp": { "type": "array", "items": { "type": "integer" }, "description": "One value per entry of `months`, same order. Whole CLP." }, "production_total_clp": { "type": "integer" }, "production_source": { "type": "string", "enum": [ "clinic_mirror", "vitrina" ] }, "occupancy_pct": { "type": "array", "items": { "type": [ "number", "null" ] } }, "occupancy_pct_total": { "type": [ "number", "null" ], "description": "Percent, one decimal." }, "costo_hora_disponible_clp": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "costo_hora_disponible_total_clp": { "type": [ "integer", "null" ] }, "costo_hora_atendida_clp": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "costo_hora_atendida_total_clp": { "type": [ "integer", "null" ] }, "produccion_hora_atendida_clp": { "type": "array", "items": { "type": [ "integer", "null" ] } }, "produccion_hora_atendida_total_clp": { "type": [ "integer", "null" ] }, "branches": { "type": "array", "items": { "type": "object", "properties": { "branch_id": { "type": "string" }, "name": { "type": "string" }, "chairs": { "type": "integer" }, "available_hours": { "type": "array", "items": { "type": "number" }, "description": "Hours per entry of `months`, one decimal." }, "attended_hours": { "type": "array", "items": { "type": "number" }, "description": "Hours per entry of `months`, one decimal." }, "available_hours_total": { "type": "number" }, "attended_hours_total": { "type": "number" }, "occupancy_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal." } }, "required": [ "branch_id", "name", "chairs", "available_hours", "attended_hours", "available_hours_total", "attended_hours_total", "occupancy_pct" ] } }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "chairs", "opening_hours", "appointments" ] } } }, "required": [ "base", "chairs", "chairs_source", "lunch_break_minutes", "available_hours", "attended_hours", "available_hours_total", "attended_hours_total", "production_clp", "production_total_clp", "production_source", "occupancy_pct", "occupancy_pct_total", "costo_hora_disponible_clp", "costo_hora_disponible_total_clp", "costo_hora_atendida_clp", "costo_hora_atendida_total_clp", "produccion_hora_atendida_clp", "produccion_hora_atendida_total_clp", "branches", "missing" ], "description": "Costo hora sillón (clinics only): fijos ÷ available chair-hours (chairs × opening hours), all costs ÷ attended hours, occupancy and production per attended hour, per branch and total." } }, "required": [ "from", "to", "current_month", "currency", "is_clinic", "reference_month", "months", "equilibrio", "equilibrio_produccion", "period", "accounts", "dentist_share", "hora_sillon" ] }, "FinanzasCostosSettings": { "type": "object", "properties": { "reference_share_enabled": { "type": "boolean", "description": "Show the reference line next to the dentist share." }, "reference_share_bps": { "type": "integer", "description": "Its share of income in basis points (3333 = a third)." }, "professional_account_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" }, "description": "The accounts that are the treating dentist’s share (with everything under them); null = detected from the plan de cuentas." }, "effective_professional_account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "chairs_override": { "type": [ "integer", "null" ], "description": "Chairs the owner says the clinic has (1–200); wins over the resources. Null = count the clinic’s resources." }, "lunch_break_minutes": { "type": [ "integer", "null" ], "description": "Weekday lunch break in minutes taken off the available chair-hours; null = the default, 60." }, "updated_by": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "reference_share_enabled", "reference_share_bps", "professional_account_ids", "effective_professional_account_ids", "chairs_override", "lunch_break_minutes", "updated_by", "updated_at" ] }, "FinanzasResumenCash": { "type": [ "object", "null" ], "properties": { "today_clp": { "type": "integer", "description": "«Caja hoy»: today’s balance of the operating accounts (savings apart) = the Flujo de caja opening." }, "balance_as_of": { "type": [ "string", "null" ] }, "accounts_count": { "type": "integer" }, "unknown_count": { "type": "integer", "description": "Operating accounts with no known balance (not in the total)." }, "savings_clp": { "type": "integer" }, "month_end": { "type": "object", "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer", "description": "The confirmed balance: bank balances plus known items only (no typical income, no «Vencidas sin pago visto»)." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income of the last 90 days (the dashed line). Never a headline." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. Read `expected_balance_clp`." } }, "required": [ "date", "balance_clp", "expected_balance_clp", "band" ], "description": "Projected balance at the end of the month." }, "in_30_days": { "type": "object", "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer", "description": "The confirmed balance: bank balances plus known items only (no typical income, no «Vencidas sin pago visto»)." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income of the last 90 days (the dashed line). Never a headline." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. Read `expected_balance_clp`." } }, "required": [ "date", "balance_clp", "expected_balance_clp", "band" ], "description": "Projected balance 30 days from today." }, "lowest": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCashFlowLowest" }, { "description": "Lowest balance over today … today + 30, today included: never above `today_clp`; `is_today` when today is the lowest." } ] }, "runs_out": { "type": [ "object", "null" ], "properties": { "date": { "type": "string", "description": "The first projected day under zero." }, "covered_until": { "type": "string", "description": "«Alcanza hasta el …»: the day before." }, "balance_clp": { "type": "integer" }, "cause": { "$ref": "#/components/schemas/FinanzasCashFlowItem" } }, "required": [ "date", "covered_until", "balance_clp", "cause" ], "description": "Null when the confirmed balance stays ≥ 0 for 30 days. `cause` is the payment that takes it below zero (that day’s biggest payment when it already starts below zero)." }, "overdue": { "type": "object", "properties": { "payables_clp": { "type": "integer" }, "payables_count": { "type": "integer" }, "stale_payables_clp": { "type": "integer" }, "stale_payables_count": { "type": "integer" }, "receivables_clp": { "type": "integer" }, "receivables_count": { "type": "integer" } }, "required": [ "payables_clp", "payables_count", "stale_payables_clp", "stale_payables_count", "receivables_clp", "receivables_count" ] }, "overdue_no_payment_seen": { "$ref": "#/components/schemas/FinanzasCashFlowOverdueNoPaymentSeen" }, "inherited_overdue": { "$ref": "#/components/schemas/FinanzasInheritedOverdue" }, "points": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "balance_clp": { "type": "integer", "description": "The confirmed balance: bank balances plus known items only (no typical income, no «Vencidas sin pago visto»)." }, "expected_balance_clp": { "type": "integer", "description": "«Con cobros esperados»: the confirmed balance plus the typical weekday income of the last 90 days (the dashed line). Never a headline." }, "band": { "type": [ "object", "null" ], "properties": { "low_clp": { "type": "integer" }, "high_clp": { "type": "integer" } }, "required": [ "low_clp", "high_clp" ], "description": "Retired with the uncertainty band (#6993): always null. Read `expected_balance_clp`." } }, "required": [ "date", "balance_clp", "expected_balance_clp", "band" ] }, "description": "The runway: one point per day, today … today + 30." } }, "required": [ "today_clp", "balance_as_of", "accounts_count", "unknown_count", "savings_clp", "month_end", "in_30_days", "lowest", "runs_out", "overdue", "overdue_no_payment_seen", "inherited_overdue", "points" ] }, "FinanzasResumenResult": { "type": [ "object", "null" ], "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "proforma": { "type": "boolean" }, "ingresos_clp": { "type": "integer", "description": "Net, as the Resultado." }, "gastos_clp": { "type": "integer", "description": "«¿Cuánto gasto?»: variables + fijos." }, "variables_clp": { "type": "integer" }, "fijos_clp": { "type": "integer" }, "sin_clasificar_clp": { "type": "integer", "description": "Part of `variables_clp`: «Egresos sin clasificar», shown apart." }, "resultado_clp": { "type": "integer", "description": "The month’s Resultado operacional." }, "produccion_clp": { "type": [ "integer", "null" ], "description": "Clinics with production data: the month’s producción (performed work in the clinic system). Null for the others." }, "basis": { "type": "string", "enum": [ "produccion", "ingresos" ], "description": "What `basis_clp`, `cobertura_pct` and `brecha_clp` measure against the break-even: `produccion` mid-month for a clinic with production data (booked income reads near zero until the month’s summary boleta arrives), `ingresos` otherwise and once booked income covers 80 % of the month’s producción." }, "basis_clp": { "type": "integer", "description": "The amount on `basis`." }, "equilibrio": { "type": [ "object", "null" ], "properties": { "month": { "type": "string", "description": "The newest month used." }, "label": { "type": "string" }, "equilibrio_clp": { "type": [ "integer", "null" ], "description": "The bar: the average break-even of the last 3 complete months, «Mes incompleto» skipped. Never null today (the whole `equilibrio` is null instead); kept nullable for compatibility." }, "sin_calculo": { "type": [ "string", "null" ], "enum": [ "sin_ingresos", "margen_no_positivo" ], "description": "Always null: only months with a break-even are averaged." }, "from": { "type": "string", "description": "First month of the average, `YYYY-MM`." }, "to": { "type": "string", "description": "Last month of the average, `YYYY-MM`." }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "equilibrio_clp": { "type": "integer" } }, "required": [ "month", "label", "equilibrio_clp" ] }, "description": "The trailing complete months used, oldest first (at most 3)." }, "produccion": { "$ref": "#/components/schemas/FinanzasEquilibrioProduccion" }, "skipped_incompleto": { "type": [ "object", "null" ], "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "message": { "type": "string", "description": "Spanish, ready for the tooltip." } }, "required": [ "month", "label", "message" ], "description": "The newest «Mes incompleto» the bar skipped, so the card can flag it like Resultado and Costos do. Null when no month was skipped." } }, "required": [ "month", "label", "equilibrio_clp", "sin_calculo", "from", "to", "months", "produccion", "skipped_incompleto" ], "description": "The break-even bar the month is judged against. Null when no complete month has a break-even yet." }, "target_clp": { "type": [ "integer", "null" ], "description": "The break-even on the same terms as `basis`: `equilibrio.produccion.equilibrio_clp` when `basis` is `produccion` and a ratio exists, else `equilibrio.equilibrio_clp`. Null without a break-even." }, "cobertura_pct": { "type": [ "number", "null" ], "description": "`basis_clp` ÷ `target_clp`, one decimal." }, "brecha_clp": { "type": [ "integer", "null" ], "description": "`basis_clp` − `target_clp` (negative: still short of it)." } }, "required": [ "month", "label", "proforma", "ingresos_clp", "gastos_clp", "variables_clp", "fijos_clp", "sin_clasificar_clp", "resultado_clp", "produccion_clp", "basis", "basis_clp", "equilibrio", "target_clp", "cobertura_pct", "brecha_clp" ] }, "FinanzasResumen": { "type": "object", "properties": { "as_of": { "type": "string", "description": "Today (America/Santiago)." }, "month": { "type": "string" }, "month_label": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP" ] }, "reports_visible": { "type": "boolean", "description": "False for a caller without `finanzas_reports:read` (the «Finanzas» staff permission): `cash` and `result` are null." }, "synced_at": { "type": [ "string", "null" ], "description": "The newest successful bank / Mercado Pago sync." }, "problem": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cash_runs_out" ] }, "date": { "type": "string" }, "balance_clp": { "type": "integer" } }, "required": [ "kind", "date", "balance_clp" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "connection" ] }, "connection_id": { "type": "string" }, "institution_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ok", "first_sync", "pending", "stale", "error", "login_required", "disconnected" ] } }, "required": [ "kind", "connection_id", "institution_name", "status" ] }, { "type": "null" } ], "description": "The one problem shown in red: cash running out within 30 days first, else a bank connection that needs a person." }, "cash": { "$ref": "#/components/schemas/FinanzasResumenCash" }, "result": { "$ref": "#/components/schemas/FinanzasResumenResult" }, "inbox": { "allOf": [ { "$ref": "#/components/schemas/FinanzasCaseCount" }, { "type": "object", "properties": { "close": { "type": [ "object", "null" ], "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "ready_to_close", "closed", "closed_imported" ] }, "open_cases": { "type": "integer" } }, "required": [ "month", "label", "state", "open_cases" ], "description": "The previous month, for «Cerrar {mes}» when nothing is open. Null (no prompt) when that month is before the month the add-on became active and holds no bank movements or documents." } }, "required": [ "close" ] } ] }, "automatic": { "type": "object", "properties": { "month": { "type": "string" }, "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "unreviewed_count": { "type": "integer" }, "by_actor": { "type": "object", "properties": { "rule": { "type": "integer" }, "match": { "type": "integer" }, "ai": { "type": "integer" } }, "required": [ "rule", "match", "ai" ] }, "recent": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/FinanzasAutomaticAction" }, { "type": "object", "properties": { "group_name": { "type": "string" }, "group_key": { "type": "string", "description": "The Hecho por Vitrina group of the action: `own_transfers`, `cash_deposits`, `clinic_payments`, `contraparte:` or, for the unassigned ones, `none:`." }, "group_count": { "type": "integer", "description": "Actions in the whole group this month." }, "group_total_clp": { "type": "integer" } }, "required": [ "group_name", "group_key", "group_count", "group_total_clp" ] } ] }, "description": "The newest 3 groups of automatic actions of the month, one row each: the group's newest action plus the group's count and total. Undo an action through POST /finanzas/automatic-actions/{kind}/{id}/undo." } }, "required": [ "month", "count", "total_clp", "unreviewed_count", "by_actor", "recent" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "institution_name": { "type": [ "string", "null" ] }, "number_masked": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP", "USD" ] }, "balance_clp": { "type": [ "integer", "null" ] }, "balance_as_of": { "type": [ "string", "null" ] }, "data_through": { "type": [ "string", "null" ] }, "stale": { "type": "boolean", "description": "true = no connection feeds the account and its newest movement is older than 37 days (D9): show «Datos hasta el …» as a warning with the cartola upload." }, "in_cash": { "type": "boolean", "description": "False for savings accounts (not in «Caja hoy»)." } }, "required": [ "id", "name", "institution_name", "number_masked", "type", "currency", "balance_clp", "balance_as_of", "data_through", "stale", "in_cash" ] } } }, "required": [ "as_of", "month", "month_label", "currency", "reports_visible", "synced_at", "problem", "cash", "result", "inbox", "automatic", "accounts" ] }, "FinanzasPuente": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "current_month": { "type": "string" }, "currency": { "type": "string", "enum": [ "CLP" ] }, "is_clinic": { "type": "boolean" }, "source": { "type": [ "string", "null" ], "enum": [ "clinic_mirror", "vitrina" ], "description": "Where producción and cobrado come from: the clinic system mirror (Dentalink/Medilink) or Vitrina’s own registers. Never both." }, "boletas_source": { "type": "string", "enum": [ "finanzas", "clinic_register", "none" ] }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "label": { "type": "string" }, "proforma": { "type": "boolean" }, "produccion_clp": { "type": "integer", "description": "Treatments performed (the clinic system’s value)." }, "cobrado_clp": { "type": "integer", "description": "Patient payments received." }, "boleteado_clp": { "type": "integer", "description": "Boletas issued (DTE 39/41, at totals), minus notas de crédito on boletas." }, "por_cobrar_clp": { "type": "integer", "description": "Produced and not paid in the period, per patient." }, "anticipos_clp": { "type": "integer", "description": "Paid and not produced in the period, per patient." }, "cobrado_sin_boleta_clp": { "type": "integer" }, "boletas_sin_pago_clp": { "type": "integer" }, "ingresos_resultado_clp": { "type": "integer", "description": "The Resultado’s «Ingresos» (issued documents, net) for the same months." }, "pagos_sin_boleta": { "type": "integer", "minimum": 0, "description": "Payments (or payment parts) without a boleta: the count behind `cobrado_sin_boleta_clp`." }, "pendiente_resumen_clp": { "type": "integer", "description": "Part of `cobrado_sin_boleta_clp` waiting for next month’s summary boleta, which is not issued yet (reason `resumen_pendiente`). Included in `cobrado_sin_boleta_clp`." }, "pagos_pendiente_resumen": { "type": "integer", "minimum": 0, "description": "Count behind `pendiente_resumen_clp`; included in `pagos_sin_boleta`." }, "boleteado_otro_mes_clp": { "type": "integer", "description": "Signed: payments of the previous month covered by THIS month’s summary boleta (+), minus payments of this month covered by the NEXT month’s summary (−). cobrado − cobrado_sin_boleta + boletas_sin_pago + boleteado_otro_mes = boleteado, apart from notas de crédito that name no boleta (they lower `boleteado_clp` but not a boleta’s capacity)." } }, "required": [ "month", "label", "proforma", "produccion_clp", "cobrado_clp", "boleteado_clp", "por_cobrar_clp", "anticipos_clp", "cobrado_sin_boleta_clp", "boletas_sin_pago_clp", "ingresos_resultado_clp", "pagos_sin_boleta", "pendiente_resumen_clp", "pagos_pendiente_resumen", "boleteado_otro_mes_clp" ] } }, "total": { "type": "object", "properties": { "produccion_clp": { "type": "integer", "description": "Treatments performed (the clinic system’s value)." }, "cobrado_clp": { "type": "integer", "description": "Patient payments received." }, "boleteado_clp": { "type": "integer", "description": "Boletas issued (DTE 39/41, at totals), minus notas de crédito on boletas." }, "por_cobrar_clp": { "type": "integer", "description": "Produced and not paid in the period, per patient." }, "anticipos_clp": { "type": "integer", "description": "Paid and not produced in the period, per patient." }, "cobrado_sin_boleta_clp": { "type": "integer" }, "boletas_sin_pago_clp": { "type": "integer" }, "ingresos_resultado_clp": { "type": "integer", "description": "The Resultado’s «Ingresos» (issued documents, net) for the same months." }, "pagos_sin_boleta": { "type": "integer", "minimum": 0, "description": "Payments (or payment parts) without a boleta: the count behind `cobrado_sin_boleta_clp`." }, "pendiente_resumen_clp": { "type": "integer", "description": "Part of `cobrado_sin_boleta_clp` waiting for next month’s summary boleta, which is not issued yet (reason `resumen_pendiente`). Included in `cobrado_sin_boleta_clp`." }, "pagos_pendiente_resumen": { "type": "integer", "minimum": 0, "description": "Count behind `pendiente_resumen_clp`; included in `pagos_sin_boleta`." }, "boleteado_otro_mes_clp": { "type": "integer", "description": "Signed: payments of the previous month covered by THIS month’s summary boleta (+), minus payments of this month covered by the NEXT month’s summary (−). cobrado − cobrado_sin_boleta + boletas_sin_pago + boleteado_otro_mes = boleteado, apart from notas de crédito that name no boleta (they lower `boleteado_clp` but not a boleta’s capacity)." } }, "required": [ "produccion_clp", "cobrado_clp", "boleteado_clp", "por_cobrar_clp", "anticipos_clp", "cobrado_sin_boleta_clp", "boletas_sin_pago_clp", "ingresos_resultado_clp", "pagos_sin_boleta", "pendiente_resumen_clp", "pagos_pendiente_resumen", "boleteado_otro_mes_clp" ], "description": "The range, netted per patient." }, "payments_without_boleta": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "clinic_mirror", "vitrina" ] }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "without_boleta_clp": { "type": "integer" }, "reason": { "type": "string", "enum": [ "sin_boleta", "boleta_no_encontrada", "resumen_pendiente" ] }, "folios": { "type": "array", "items": { "type": "string" } }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Full name; «Paciente A. P.» for a caller without the patient roster." }, "rut": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut" ] } }, "required": [ "payment_id", "source", "day", "amount_clp", "without_boleta_clp", "reason", "folios", "patient" ] } }, "by_month": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "clinic_mirror", "vitrina" ] }, "day": { "type": "string" }, "amount_clp": { "type": "integer" }, "without_boleta_clp": { "type": "integer" }, "reason": { "type": "string", "enum": [ "sin_boleta", "boleta_no_encontrada", "resumen_pendiente" ] }, "folios": { "type": "array", "items": { "type": "string" } }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Full name; «Paciente A. P.» for a caller without the patient roster." }, "rut": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "rut" ] } }, "required": [ "payment_id", "source", "day", "amount_clp", "without_boleta_clp", "reason", "folios", "patient" ] } } }, "required": [ "month", "count", "total_clp", "items" ] }, "description": "Months with a gap, ascending, each with its `per_month` largest items (patients redacted like `items`)." } }, "required": [ "count", "total_clp", "items", "by_month" ] }, "boletas_without_payment": { "type": "object", "properties": { "count": { "type": "integer" }, "total_clp": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "day": { "type": "string" }, "total_clp": { "type": "integer" }, "without_payment_clp": { "type": "integer" }, "receiver": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "rut": { "type": [ "string", "null" ] }, "patient_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "name", "rut", "patient_id" ] }, "monthly_summary": { "type": "boolean" } }, "required": [ "document_id", "dte_type", "folio", "day", "total_clp", "without_payment_clp", "receiver", "monthly_summary" ] } } }, "required": [ "count", "total_clp", "items" ] }, "monthly_boletas": { "type": "array", "items": { "type": "object", "properties": { "document_id": { "type": "string" }, "dte_type": { "type": [ "integer", "null" ] }, "folio": { "type": [ "string", "null" ] }, "day": { "type": "string" }, "month": { "type": "string" }, "total_clp": { "type": "integer" }, "covered_clp": { "type": "integer" }, "payments": { "type": "integer" } }, "required": [ "document_id", "dte_type", "folio", "day", "month", "total_clp", "covered_clp", "payments" ] } } }, "required": [ "from", "to", "current_month", "currency", "is_clinic", "source", "boletas_source", "months", "total", "payments_without_boleta", "boletas_without_payment", "monthly_boletas" ] }, "FinanzasAdsConnections": { "type": "object", "properties": { "profile": { "type": "boolean", "description": "The workspace has its ad-data link (provisioned when it connects Meta Ads)." }, "last_attempt_at": { "type": [ "string", "null" ] }, "last_sync_at": { "type": [ "string", "null" ] }, "last_error": { "type": [ "string", "null" ], "description": "Spanish copy when the last read failed, else null." }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "meta_ads", "google_ads" ] }, "label": { "type": "string", "example": "Meta Ads" }, "status": { "type": "string", "enum": [ "connected", "expired", "none" ], "description": "connected = at least one healthy account; expired = accounts, none healthy; none = no account." }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "meta_ads", "google_ads", "tiktok_ads" ] }, "ad_account_id": { "type": "string", "description": "The platform's own id: Meta `act_…`, Google the 10-digit customer id.", "example": "act_969938652650502" }, "account_label": { "type": "string", "description": "Google: `123-456-7890`; Meta: the `act_…` id." }, "account_name": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "connection_status": { "type": "string", "description": "connected | syncing | error | disconnected | reconnect_required | revoked" }, "healthy": { "type": "boolean", "description": "connected or syncing." }, "last_synced_at": { "type": [ "string", "null" ] }, "charges_supported": { "type": "boolean", "description": "True only for Meta." }, "charges_synced_at": { "type": [ "string", "null" ], "description": "When Meta's activity log was last read in full; null = never." }, "charges_synced": { "type": "integer" }, "charges_linked": { "type": "integer" }, "charges_unreconciled": { "type": "integer", "description": "Billing charges older than a week that no card line has been matched to («por conciliar»)." }, "spend_by_month": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "example": "2026-10" }, "spend_minor": { "type": "integer" }, "currency": { "type": [ "string", "null" ] } }, "required": [ "month", "spend_minor", "currency" ] }, "description": "Spend per month over the last read (92 days), smallest unit of `currency`." } }, "required": [ "platform", "ad_account_id", "account_label", "account_name", "currency", "timezone", "connection_status", "healthy", "last_synced_at", "charges_supported", "charges_synced_at", "charges_synced", "charges_linked", "charges_unreconciled", "spend_by_month" ] } }, "without_connection": { "type": "string" }, "connect_path": { "type": "string", "description": "Where to connect: Integraciones › Meta Ads (no connect flow here)." } }, "required": [ "platform", "label", "status", "accounts", "without_connection", "connect_path" ] } } }, "required": [ "profile", "last_attempt_at", "last_sync_at", "last_error", "platforms" ] }, "FinanzasAdsCharge": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string", "enum": [ "meta_ads", "google_ads", "tiktok_ads" ] }, "ad_account_id": { "type": "string" }, "event_type": { "type": "string" }, "event_label": { "type": "string", "description": "cargo | reembolso | contracargo | rechazo | fondos" }, "event_time": { "type": "string" }, "local_date": { "type": "string" }, "meta_transaction_id": { "type": [ "string", "null" ], "description": "Meta's «Transaction ID» (Billing & payments), unique per charge." }, "amount_minor": { "type": [ "integer", "null" ], "description": "Smallest unit of `currency` (CLP pesos, USD cents). Null when Meta stated none." }, "currency": { "type": [ "string", "null" ] }, "link_state": { "type": "string", "enum": [ "linked", "unlinked" ] }, "document_id": { "type": [ "string", "null" ] }, "movement_id": { "type": [ "string", "null" ] }, "linked_at": { "type": [ "string", "null" ] } }, "required": [ "id", "platform", "ad_account_id", "event_type", "event_label", "event_time", "local_date", "meta_transaction_id", "amount_minor", "currency", "link_state", "document_id", "movement_id", "linked_at" ] }, "FinanzasAdsChargesList": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/FinanzasAdsCharge" } }, "totals": { "type": "object", "properties": { "count": { "type": "integer" }, "linked": { "type": "integer" }, "unlinked": { "type": "integer" } }, "required": [ "count", "linked", "unlinked" ] } }, "required": [ "from", "to", "items", "totals" ] }, "FinanzasAdsSyncResult": { "type": "object", "properties": { "skipped": { "type": "boolean" }, "read": { "type": "string", "enum": [ "ok", "no_profile", "error", "skipped" ] }, "accounts": { "type": "integer" }, "charges_new": { "type": "integer" }, "recognize": { "type": "object", "properties": { "recognized": { "type": "integer" }, "created": { "type": "integer" }, "receipt_first": { "type": "integer" } }, "required": [ "recognized", "created", "receipt_first" ] }, "match": { "type": "object", "properties": { "open": { "type": "integer" }, "linked": { "type": "integer" }, "unconfirmed": { "type": "integer" }, "no_connection": { "type": "integer" }, "pending": { "type": "integer" } }, "required": [ "open", "linked", "unconfirmed", "no_connection", "pending" ] } }, "required": [ "skipped", "read", "accounts", "charges_new", "recognize", "match" ] }, "ClinicImportedBalanceBudget": { "type": "object", "properties": { "budget_id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string", "example": "E-412" }, "status": { "type": "string", "example": "accepted" }, "external_id": { "type": [ "string", "null" ], "example": "18233" }, "plan_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-28" }, "cutover_balance_clp": { "type": "integer" }, "collected_clp": { "type": "integer" }, "balance_clp": { "type": "integer" } }, "required": [ "budget_id", "display_id", "status", "external_id", "plan_date", "cutover_balance_clp", "collected_clp", "balance_clp" ] }, "ClinicImportedBalanceRow": { "type": "object", "properties": { "patient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "nombre": { "type": [ "string", "null" ] }, "apellidos": { "type": [ "string", "null" ] }, "rut": { "type": [ "string", "null" ] }, "numero_ficha": { "type": [ "string", "null" ] } }, "required": [ "id", "nombre", "apellidos", "rut", "numero_ficha" ] }, "balance_clp": { "type": "integer" }, "cutover_balance_clp": { "type": "integer" }, "collected_clp": { "type": "integer" }, "last_vendor_payment_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-28" }, "last_collected_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-28" }, "last_payment_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-28" }, "budgets": { "type": "array", "items": { "$ref": "#/components/schemas/ClinicImportedBalanceBudget" } } }, "required": [ "patient", "balance_clp", "cutover_balance_clp", "collected_clp", "last_vendor_payment_on", "last_collected_on", "last_payment_on", "budgets" ] }, "ClinicImportedBalanceList": { "type": "object", "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ClinicImportedBalanceRow" } }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "limit": { "type": "integer" }, "summary": { "type": "object", "properties": { "patients": { "type": "integer" }, "balance_clp": { "type": "integer" }, "cutover_balance_clp": { "type": "integer" }, "collected_clp": { "type": "integer" } }, "required": [ "patients", "balance_clp", "cutover_balance_clp", "collected_clp" ] } }, "required": [ "rows", "total", "offset", "limit", "summary" ] }, "ClinicImportedBalanceDetail": { "type": "object", "properties": { "budget_id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "status": { "type": "string" }, "clinic_patient_id": { "type": "string", "format": "uuid" }, "cutover_balance_clp": { "type": "integer" }, "balance_clp": { "type": "integer" }, "payer": { "type": [ "object", "null" ], "properties": { "contact_id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "contact_id", "name" ] }, "will_bond_payer": { "type": "boolean" }, "credits": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "paid_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "example": "2026-10-28" }, "instrument": { "type": "string" }, "amount_clp": { "type": "integer" }, "unallocated_clp": { "type": "integer" } }, "required": [ "payment_id", "paid_on", "instrument", "amount_clp", "unallocated_clp" ] } } }, "required": [ "budget_id", "display_id", "status", "clinic_patient_id", "cutover_balance_clp", "balance_clp", "payer", "will_bond_payer", "credits" ] }, "ClinicImportedBalanceCollectResult": { "type": "object", "properties": { "budget_id": { "type": "string", "format": "uuid" }, "display_id": { "type": "string" }, "clinic_patient_id": { "type": "string", "format": "uuid" }, "applied_clp": { "type": "integer" }, "balance_before_clp": { "type": "integer" }, "balance_after_clp": { "type": "integer" }, "obligation_group_id": { "type": [ "string", "null" ], "format": "uuid" }, "obligation_id": { "type": [ "string", "null" ], "format": "uuid" }, "payer_bond_id": { "type": [ "string", "null" ], "format": "uuid" }, "payment": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] }, "applied": { "type": "array", "items": { "type": "object", "properties": {} } }, "surplus_clp": { "type": "integer" }, "reasons": { "type": "array", "items": { "type": "string" } }, "replayed": { "type": "boolean" } }, "required": [ "payment", "applied", "surplus_clp", "reasons", "replayed" ] } }, "required": [ "budget_id", "display_id", "clinic_patient_id", "applied_clp", "balance_before_clp", "balance_after_clp", "obligation_group_id", "obligation_id", "payer_bond_id", "payment" ] }, "AudienceLabels": { "type": "object", "properties": { "tags": { "type": "object", "additionalProperties": { "type": "string" } }, "pipelines": { "type": "object", "additionalProperties": { "type": "string" } }, "stages": { "type": "object", "additionalProperties": { "type": "string" } }, "custom_attributes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "label": { "type": "string" }, "data_type": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "data_type", "options" ] } }, "interest_topics": { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "parent_name": { "type": [ "string", "null" ] } }, "required": [ "name", "kind", "parent_name" ] } }, "missing": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } }, "pipeline_id": { "type": [ "string", "null" ] }, "stage_id": { "type": [ "string", "null" ] }, "custom_attributes": { "type": "array", "items": { "type": "string" } }, "interest_topics": { "type": "array", "items": { "type": "string" } } }, "required": [ "tags", "pipeline_id", "stage_id", "custom_attributes", "interest_topics" ] } }, "required": [ "tags", "pipelines", "stages", "custom_attributes", "interest_topics", "missing" ] }, "AudienceSummary": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "filter": { "type": "object", "properties": { "lifecycle_stages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "tag_ids_any": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 25 }, "tag_ids_all": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "tag_ids_none": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 25 }, "countries": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "maxItems": 25 }, "languages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 }, "maxItems": 25 }, "has_channel": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp", "email" ] }, "maxItems": 2 }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "created_after": { "type": "string", "format": "date-time" }, "created_before": { "type": "string", "format": "date-time" }, "birthday_months": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 }, "maxItems": 12 }, "birthday_within_days": { "type": "integer", "minimum": 1, "maximum": 366 }, "vehicle_brands": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 25 }, "vehicle_models": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 25 }, "vehicle_years": { "type": "array", "items": { "type": "integer", "minimum": 1900, "maximum": 2100 }, "maxItems": 50 }, "custom_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "maxLength": 500 }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxItems": 25 } }, "required": [ "key" ] }, "maxItems": 10 }, "interests": { "type": "object", "properties": { "topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 25 }, "within_days": { "type": "integer", "minimum": 1, "maximum": 1095 }, "min_strength": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "include_past": { "type": "boolean" } }, "required": [ "topic_ids" ], "additionalProperties": false }, "interests_none": { "type": "object", "properties": { "topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 25 }, "min_strength": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "include_past": { "type": "boolean" } }, "required": [ "topic_ids" ], "additionalProperties": false } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "dynamic", "static", "mixed", "all" ] }, "include_count": { "type": "integer" }, "exclude_count": { "type": "integer" }, "labels": { "$ref": "#/components/schemas/AudienceLabels" }, "usage": { "type": "object", "properties": { "campaigns_count": { "type": "integer" }, "last_used_at": { "type": [ "string", "null" ] }, "active_campaigns_count": { "type": "integer" } }, "required": [ "campaigns_count", "last_used_at", "active_campaigns_count" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "description", "filter", "kind", "include_count", "exclude_count", "labels", "usage", "created_by", "created_at", "updated_at" ] }, "AudienceDetail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "filter": { "type": "object", "properties": { "lifecycle_stages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 10 }, "tag_ids_any": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 25 }, "tag_ids_all": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "tag_ids_none": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 25 }, "countries": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "maxItems": 25 }, "languages": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 20 }, "maxItems": 25 }, "has_channel": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp", "email" ] }, "maxItems": 2 }, "pipeline_id": { "type": "string", "format": "uuid" }, "stage_id": { "type": "string", "format": "uuid" }, "created_after": { "type": "string", "format": "date-time" }, "created_before": { "type": "string", "format": "date-time" }, "birthday_months": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 12 }, "maxItems": 12 }, "birthday_within_days": { "type": "integer", "minimum": 1, "maximum": 366 }, "vehicle_brands": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 25 }, "vehicle_models": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 25 }, "vehicle_years": { "type": "array", "items": { "type": "integer", "minimum": 1900, "maximum": 2100 }, "maxItems": 50 }, "custom_attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "maxLength": 500 }, "values": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxItems": 25 } }, "required": [ "key" ] }, "maxItems": 10 }, "interests": { "type": "object", "properties": { "topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 25 }, "within_days": { "type": "integer", "minimum": 1, "maximum": 1095 }, "min_strength": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "include_past": { "type": "boolean" } }, "required": [ "topic_ids" ], "additionalProperties": false }, "interests_none": { "type": "object", "properties": { "topic_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 25 }, "min_strength": { "anyOf": [ { "type": "number", "enum": [ 1 ] }, { "type": "number", "enum": [ 2 ] }, { "type": "number", "enum": [ 3 ] }, { "type": "number", "enum": [ 4 ] } ] }, "include_past": { "type": "boolean" } }, "required": [ "topic_ids" ], "additionalProperties": false } }, "additionalProperties": false }, "kind": { "type": "string", "enum": [ "dynamic", "static", "mixed", "all" ] }, "include_count": { "type": "integer" }, "exclude_count": { "type": "integer" }, "labels": { "$ref": "#/components/schemas/AudienceLabels" }, "usage": { "type": "object", "properties": { "campaigns_count": { "type": "integer" }, "last_used_at": { "type": [ "string", "null" ] }, "active_campaigns_count": { "type": "integer" }, "active_campaigns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "scheduled_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "status", "scheduled_at" ] } } }, "required": [ "campaigns_count", "last_used_at", "active_campaigns_count", "active_campaigns" ] }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "include_contact_ids": { "type": "array", "items": { "type": "string" } }, "exclude_contact_ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "description", "filter", "kind", "include_count", "exclude_count", "labels", "usage", "created_by", "created_at", "updated_at", "include_contact_ids", "exclude_contact_ids" ] }, "AudienceConditionData": { "type": "object", "properties": { "vehicle": { "type": "boolean" } }, "required": [ "vehicle" ] }, "AudienceStats": { "type": "object", "properties": { "id": { "type": "string" }, "total": { "type": "integer" }, "whatsapp_reachable": { "type": "integer" }, "email_reachable": { "type": "integer" }, "computed_at": { "type": "string" }, "partial": { "type": "boolean" } }, "required": [ "id", "total", "whatsapp_reachable", "email_reachable", "computed_at", "partial" ] }, "AudienceOverlap": { "type": "object", "properties": { "a": { "type": "object", "properties": { "id": { "type": "string" }, "total": { "type": "integer" } }, "required": [ "id", "total" ] }, "b": { "type": "object", "properties": { "id": { "type": "string" }, "total": { "type": "integer" } }, "required": [ "id", "total" ] }, "both": { "type": "integer" }, "a_only": { "type": "integer" }, "b_only": { "type": "integer" } }, "required": [ "a", "b", "both", "a_only", "b_only" ] }, "AudienceChannelReach": { "type": "object", "properties": { "reachable": { "type": "integer" }, "no_identifier": { "type": "integer" }, "invalid_identifier": { "type": "integer" }, "duplicate": { "type": "integer" }, "opted_out": { "type": "integer" }, "opted_out_by": { "type": "object", "properties": { "stop_keyword": { "type": "integer" }, "unsubscribe": { "type": "integer" }, "bounce": { "type": "integer" }, "complaint": { "type": "integer" }, "manual": { "type": "integer" }, "classified": { "type": "integer" }, "scope_blocked": { "type": "integer" }, "all_proactive_blocked": { "type": "integer" } } }, "invalid_by": { "type": "object", "properties": { "too_short": { "type": "integer" }, "landline": { "type": "integer" }, "malformed": { "type": "integer" } } } }, "required": [ "reachable", "no_identifier", "invalid_identifier", "duplicate", "opted_out", "opted_out_by", "invalid_by" ] }, "AudienceCounts": { "type": [ "object", "null" ], "properties": { "total": { "type": "integer" }, "by_source": { "type": "object", "properties": { "rule": { "type": "integer" }, "manual": { "type": "integer" }, "rule_and_manual": { "type": "integer" } }, "required": [ "rule", "manual", "rule_and_manual" ] }, "overrides": { "type": "object", "properties": { "included": { "type": "integer" }, "included_not_member": { "type": "integer" }, "excluded": { "type": "integer" }, "excluded_would_match": { "type": "integer" } }, "required": [ "included", "included_not_member", "excluded", "excluded_would_match" ] }, "omitted": { "type": "object", "properties": { "archived": { "type": "integer" }, "blocked": { "type": "integer" }, "spam": { "type": "integer" }, "merged": { "type": "integer" }, "import_only": { "type": "integer" }, "excluded": { "type": "integer" } }, "required": [ "archived", "blocked", "spam", "merged", "import_only", "excluded" ] }, "channels": { "type": "object", "properties": { "whatsapp": { "$ref": "#/components/schemas/AudienceChannelReach" }, "email": { "$ref": "#/components/schemas/AudienceChannelReach" } }, "required": [ "whatsapp", "email" ] }, "computed_at": { "type": "string" }, "partial": { "type": "boolean" }, "cap": { "type": "integer" }, "whatsapp_eligible": { "type": "integer", "description": "TRANSITIONAL: channels.whatsapp.reachable + opted_out" }, "whatsapp_suppressed": { "type": "integer", "description": "TRANSITIONAL: channels.whatsapp.opted_out" }, "suppressed_is_partial": { "type": "boolean", "description": "TRANSITIONAL: = partial" } }, "required": [ "total", "by_source", "overrides", "omitted", "channels", "computed_at", "partial", "cap", "whatsapp_eligible", "whatsapp_suppressed", "suppressed_is_partial" ] }, "AudienceOverridesResult": { "type": "object", "properties": { "applied": { "type": "integer" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": [ "string", "null" ] }, "input": { "type": "string" }, "result": { "type": "string", "enum": [ "added", "removed", "already", "not_found", "moderated", "already_member_by_rule" ] } }, "required": [ "contact_id", "result" ] } }, "include_count": { "type": "integer" }, "exclude_count": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "applied", "outcomes", "include_count", "exclude_count", "updated_at" ] }, "MessagingBudget": { "type": "object", "properties": { "messaging_account_id": { "type": "string", "format": "uuid" }, "account_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "This number plus the numbers counted with it (same WABA)." }, "waba_id": { "type": [ "string", "null" ] }, "tier": { "type": [ "string", "null" ], "description": "Meta's messaging-limit tier, e.g. TIER_250, TIER_2K." }, "tier_unknown": { "type": "boolean", "description": "Never observed or unrecognized — treated as no cap." }, "unlimited": { "type": "boolean" }, "quality_rating": { "type": [ "string", "null" ] }, "tier_observed_at": { "type": [ "string", "null" ] }, "limit_per_24h": { "type": [ "integer", "null" ], "description": "Unique people per rolling 24 h; null = no cap." }, "used_last_24h": { "type": "integer" }, "used_by_campaigns_last_24h": { "type": "integer" }, "used_by_other_senders_last_24h": { "type": "integer" }, "remaining": { "type": [ "integer", "null" ] }, "reserve": { "type": "integer", "description": "Kept for non-campaign senders: max(pct × limit, p95 of the daily non-campaign usage over 7 days), capped." }, "reserve_basis": { "type": "object", "properties": { "pct_floor": { "type": "integer" }, "observed_p95": { "type": "integer" } }, "required": [ "pct_floor", "observed_p95" ] }, "campaign_cap": { "type": [ "integer", "null" ] }, "campaign_headroom": { "type": [ "integer", "null" ], "description": "What campaigns may still start right now." }, "window_resets_at": { "type": [ "string", "null" ] }, "next_batch_at": { "type": [ "string", "null" ] }, "computed_at": { "type": "string" } }, "required": [ "messaging_account_id", "account_ids", "waba_id", "tier", "tier_unknown", "unlimited", "quality_rating", "tier_observed_at", "limit_per_24h", "used_last_24h", "used_by_campaigns_last_24h", "used_by_other_senders_last_24h", "remaining", "reserve", "reserve_basis", "campaign_cap", "campaign_headroom", "window_resets_at", "next_batch_at", "computed_at" ] }, "CampaignSendWindow": { "type": [ "object", "null" ], "properties": { "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "IANA zone the window is read on, e.g. America/Santiago." }, "days": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 7, "description": "ISO weekdays the window opens on: 1 = Monday … 7 = Sunday." }, "start": { "type": "string", "description": "Local opening time, HH:MM (inclusive)." }, "end": { "type": "string", "description": "Local closing time, HH:MM (exclusive); later than start." } }, "required": [ "timezone", "days", "start", "end" ], "additionalProperties": false, "description": "The window this plan used (resolved); null = contact hours only." }, "CampaignSendSchedule": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "daily" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "IANA zone, e.g. America/Santiago." }, "start_date": { "type": "string", "description": "First day (local), YYYY-MM-DD." }, "time": { "type": "string", "description": "Local time of every batch, HH:MM." }, "max_per_batch": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "At most this many people per slot, in total across the slot’s grace, even with headroom left (ADR 0139 amendment) — e.g. 100 and 100 for an even A/B on a number that gives campaigns 200 a day. Absent/null = no cap." } }, "required": [ "kind", "timezone", "start_date", "time" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "slots" ] }, "timezone": { "type": "string", "minLength": 1, "maxLength": 64, "description": "IANA zone, e.g. America/Santiago." }, "slots": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "Local date, YYYY-MM-DD." }, "time": { "type": "string", "description": "Local time, HH:MM." } }, "required": [ "date", "time" ], "additionalProperties": false }, "minItems": 1, "maxItems": 60, "description": "The batches, one per instant (stored sorted ascending)." }, "after_last": { "type": "string", "enum": [ "continue_daily", "pause" ], "description": "Recipients left after the last slot: continue every day at the last slot’s time, or pause (schedule_exhausted)." }, "max_per_batch": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "At most this many people per slot, in total across the slot’s grace, even with headroom left (ADR 0139 amendment) — e.g. 100 and 100 for an even A/B on a number that gives campaigns 200 a day. Absent/null = no cap." } }, "required": [ "kind", "timezone", "slots", "after_last" ], "additionalProperties": false }, { "type": "null" } ], "description": "The schedule this plan used (ADR 0139); null = none." }, "CampaignScheduleSimulation": { "type": [ "object", "null" ], "properties": { "batches": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "description": "The slot instant (ISO)." }, "local": { "type": "string", "description": "The slot on the schedule’s clock, e.g. «jue 15 oct, 20:00»." }, "planned": { "type": "integer", "description": "People this batch would send to." }, "slot_index": { "type": [ "integer", "null" ], "description": "Index into the sorted `slots`; null for a daily batch." }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "budget_not_freed", "partial_budget", "outside_contact_hours", "in_the_past" ] } }, "shared_with": { "type": "integer", "description": "Slots the sibling campaigns of the number are expected to use in this batch’s 24 h window (at − 24 h, at]." } }, "required": [ "at", "local", "planned", "slot_index", "warnings", "shared_with" ] } }, "covers_all": { "type": "boolean" }, "remaining_after_last": { "type": "integer" }, "completes_at": { "type": [ "string", "null" ], "description": "The slot that sends the last person; null when it never does." }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "slot_in_past", "duplicate_slot", "too_close", "uncovered", "asap_not_allowed", "shared_budget_hint" ] }, "slot_index": { "type": "integer" }, "message_es": { "type": "string" }, "message_en": { "type": "string" }, "suggested_at": { "type": "string", "description": "The earliest instant that would work (ISO)." } }, "required": [ "code", "message_es", "message_en" ] } }, "tier_unknown": { "type": "boolean", "description": "No tier known for the number: no cap applied (all at the first slot)." }, "replies_handled_by": { "type": [ "string", "null" ], "enum": [ "ai", "human" ], "description": "Who answers the replies: `ai` = the AI agent the number routes to (slots outside the contact hours carry no `outside_contact_hours` warning); `human` = the team; null = unknown (warned as for the team)." }, "outside_contact_hours": { "type": "array", "items": { "type": "string" }, "description": "The batches (`local`) outside the workspace’s contact hours, whoever answers." }, "siblings": { "type": "array", "items": { "type": "object", "properties": { "campaign_id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "sending", "paused" ] }, "pending": { "type": "integer" }, "schedule_label": { "type": [ "string", "null" ], "description": "Its schedule; null = it sends continuously." }, "estimated_per_day": { "type": [ "integer", "null" ], "description": "About how many it sends per 24 h; null = no cap known on the number." } }, "required": [ "campaign_id", "name", "status", "pending", "schedule_label", "estimated_per_day" ] }, "description": "The other campaigns of the number (same WABA group) — scheduled, sending or paused with people pending — sharing its limit, oldest first. Their expected batches count against this plan (ADR 0139 amendment)." } }, "required": [ "batches", "covers_all", "remaining_after_last", "completes_at", "issues", "tier_unknown", "replies_handled_by", "outside_contact_hours", "siblings" ], "description": "With a schedule: batch by batch, against the budget (ADR 0139). Null without one." }, "CampaignSendPlan": { "type": [ "object", "null" ], "properties": { "recipients": { "type": "integer" }, "sendable_now": { "type": [ "integer", "null" ] }, "fits_now": { "type": "boolean" }, "per_window": { "type": [ "integer", "null" ] }, "windows": { "type": "integer", "description": "Sending days including the first (1 = it all fits now)." }, "estimated_completion_at": { "type": [ "string", "null" ] }, "recommended_send_mode": { "type": "string", "enum": [ "paced", "asap" ], "description": "paced: continue automatically across the rolling 24 h windows; asap: send what fits now and pause (ADR 0129)." }, "next_batch_at": { "type": [ "string", "null" ] }, "send_window": { "$ref": "#/components/schemas/CampaignSendWindow" }, "window_label": { "type": [ "string", "null" ], "description": "e.g. «lun–vie 10:00–18:00 (America/Santiago)»; null = none." }, "next_window_opens_at": { "type": [ "string", "null" ], "description": "Set when it is outside the window now: the first batch waits until then." }, "send_schedule": { "$ref": "#/components/schemas/CampaignSendSchedule" }, "schedule_label": { "type": [ "string", "null" ], "description": "e.g. «Todos los días a las 20:00 (America/Santiago) desde hoy»." }, "schedule": { "$ref": "#/components/schemas/CampaignScheduleSimulation" } }, "required": [ "recipients", "sendable_now", "fits_now", "per_window", "windows", "estimated_completion_at", "recommended_send_mode", "next_batch_at", "send_window", "window_label", "next_window_opens_at" ] }, "CampaignMessagingBudget": { "type": "object", "properties": { "budget": { "$ref": "#/components/schemas/MessagingBudget" }, "plan": { "$ref": "#/components/schemas/CampaignSendPlan" } }, "required": [ "budget", "plan" ] }, "CampaignHeaderMediaMeta": { "type": "object", "properties": { "updated_recipients": { "type": "integer", "minimum": 0, "description": "Recipients still `pending` whose frozen params now carry the new link. Already sent / delivered / read / failed ones are history and keep theirs." } }, "required": [ "updated_recipients" ] }, "CampaignHeaderMediaBody": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1, "description": "Public https link to the image / video / PDF (e.g. the `url` `POST /whatsapp-templates/header-media` returns).", "example": "https://media.example.com/promo-noviembre.jpg" } }, "required": [ "url" ], "additionalProperties": false }, "CampaignSendNowResult": { "type": "object", "properties": { "started": { "type": "boolean", "enum": [ true ] }, "waiting_for_window_until": { "type": [ "string", "null" ], "description": "Outside the send window: nothing leaves until this instant (the window opening). Null = sends now." } }, "required": [ "started", "waiting_for_window_until" ] }, "CampaignSendNowBody": { "type": "object", "properties": { "send_schedule": { "allOf": [ { "$ref": "#/components/schemas/CampaignSendSchedule" }, { "description": "When paced batches leave, as explicit instants (WhatsApp, ADR 0139). Replaces the send window when set; null = the send window / contact hours. Refused with an `asap` send_mode (400 schedule_requires_paced)." } ] } }, "additionalProperties": false }, "CampaignPreflight": { "type": "object", "properties": { "ready": { "type": "boolean", "description": "No check is `block`." }, "checks": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "template_approved | recipients | header_media | test_sent | messaging_tier | number_quality | schedule | replies | opt_out | recent_campaign_overlap (WhatsApp); template | recipients | unsubscribe | test_sent | sender_domain (email)." }, "status": { "type": "string", "enum": [ "ok", "warn", "block" ] }, "title_es": { "type": "string" }, "title_en": { "type": "string" }, "detail_es": { "type": "string" }, "detail_en": { "type": "string" }, "href": { "type": "string", "description": "App-relative link to fix it, e.g. the template or the audience." } }, "required": [ "key", "status", "title_es", "title_en" ] } }, "summary": { "type": "object", "properties": { "recipients": { "type": "integer" }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "template_name": { "type": "string" }, "schedule_label_es": { "type": "string" }, "schedule_label_en": { "type": "string" }, "first_batch_at": { "type": [ "string", "null" ] }, "completes_at": { "type": [ "string", "null" ] }, "batches_count": { "type": [ "integer", "null" ] }, "limit_per_24h": { "type": [ "integer", "null" ], "description": "The number’s Meta limit (WhatsApp); null = no cap known." }, "reserve": { "type": "integer", "description": "Kept free for reminders and other senders (WhatsApp)." }, "replies_handled_by": { "type": "string", "enum": [ "ai", "human" ], "description": "Who answers the replies (WhatsApp): the AI agent the number routes to, or the team (`reply_mode = human`, or no agent on the number)." } }, "required": [ "recipients", "channel", "schedule_label_es", "schedule_label_en", "first_batch_at", "completes_at", "batches_count" ] }, "plan": { "allOf": [ { "$ref": "#/components/schemas/CampaignScheduleSimulation" }, { "description": "«Ver plan»: the schedule simulated; null without a schedule." } ] } }, "required": [ "ready", "checks", "summary", "plan" ] }, "CampaignResumeBody": { "type": "object", "properties": { "send_mode": { "type": "string", "enum": [ "paced", "asap" ], "description": "paced: continue automatically across the rolling 24 h windows; asap: send what fits now and pause (ADR 0129)." }, "acknowledge_quality": { "type": "boolean", "description": "Resume a WhatsApp campaign although its number's quality is not GREEN (YELLOW or RED, or unknown after a `number_quality` pause). Without it such a resume answers 409 with `details.reason: number_quality_not_green` and `details.quality_rating`." } }, "additionalProperties": false }, "CampaignRecipient": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "contact_name": { "type": [ "string", "null" ] }, "identifier": { "type": "string" }, "params": { "type": "object", "additionalProperties": { "type": "string" } }, "rendered_text": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed", "suppressed" ] }, "external_message_id": { "type": [ "string", "null" ] }, "error": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": [ "string", "null" ] } }, "required": [ "code", "title", "detail" ], "description": "Meta's raw error, as it answered." }, "error_reason": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "human_es": { "type": "string" }, "human_en": { "type": "string" }, "action": { "type": "string", "enum": [ "none", "remove_number", "retry_later", "check_template" ], "description": "none: Meta decided, nothing to do; remove_number: the number cannot receive WhatsApp — take it out of the audience; retry_later: a limit or transient error; check_template: the template/variables/media must be fixed." } }, "required": [ "code", "human_es", "human_en", "action" ], "description": "The failure in plain language, with a suggested action." }, "replied_button": { "type": [ "string", "null" ], "description": "The template quick-reply button the person's first reply tapped; null when they wrote free text or did not reply." }, "sent_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "read_at": { "type": [ "string", "null" ] }, "failed_at": { "type": [ "string", "null" ] }, "replied_at": { "type": [ "string", "null" ] }, "replied_conversation_id": { "type": [ "string", "null" ], "format": "uuid" }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The conversation the send was stored in — created by the send (born closed) or the live thread it was appended to. Null before the send, or for a send the backfill has not linked yet." }, "created_at": { "type": "string" } }, "required": [ "id", "campaign_id", "contact_id", "contact_name", "identifier", "params", "rendered_text", "state", "external_message_id", "error", "error_reason", "replied_button", "sent_at", "delivered_at", "read_at", "failed_at", "replied_at", "replied_conversation_id", "created_at" ] }, "CampaignResults": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "whatsapp", "email", "voice" ] }, "funnel": { "type": "object", "properties": { "recipients": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "read": { "type": "integer" }, "replied": { "type": "integer" }, "opted_out": { "type": "integer" }, "failed": { "type": "integer" }, "suppressed": { "type": "integer" }, "pending": { "type": "integer" }, "conversations_created": { "type": "integer", "description": "Conversations this campaign's sends created («conversaciones iniciadas»). A send to a contact with a live thread is appended there and not counted." } }, "required": [ "recipients", "sent", "delivered", "read", "replied", "opted_out", "failed", "suppressed", "pending", "conversations_created" ] }, "rates": { "type": "object", "properties": { "delivered": { "type": [ "number", "null" ], "description": "delivered / sent" }, "read": { "type": [ "number", "null" ], "description": "read / delivered" }, "replied": { "type": [ "number", "null" ], "description": "replied / delivered" } }, "required": [ "delivered", "read", "replied" ], "description": "0–1 fractions; null when the denominator is 0." }, "buttons": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "text", "count" ] }, "description": "Replies whose first message was a tap on one of the template's quick-reply buttons, per button (every button listed, zeros included)." }, "free_text": { "type": "integer", "description": "Replies whose first message was not a button tap." }, "failures": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "human_es": { "type": "string" }, "human_en": { "type": "string" }, "action": { "type": "string", "enum": [ "none", "remove_number", "retry_later", "check_template" ], "description": "none: Meta decided, nothing to do; remove_number: the number cannot receive WhatsApp — take it out of the audience; retry_later: a limit or transient error; check_template: the template/variables/media must be fixed." }, "count": { "type": "integer" } }, "required": [ "code", "title", "human_es", "human_en", "action", "count" ] } }, "opt_outs": { "type": "object", "properties": { "count": { "type": "integer" }, "by_reason": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "count", "by_reason" ] }, "timeline": { "type": "object", "properties": { "unit": { "type": "string", "enum": [ "hour", "day" ] }, "timezone": { "type": "string" }, "points": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string", "description": "Bucket start (ISO, UTC)." }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "read": { "type": "integer" }, "replied": { "type": "integer" } }, "required": [ "at", "sent", "delivered", "read", "replied" ] } } }, "required": [ "unit", "timezone", "points" ] } }, "required": [ "campaign_id", "channel", "funnel", "rates", "buttons", "free_text", "failures", "opt_outs", "timeline" ] }, "CampaignMetaInsights": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ] }, "template": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" }, "external_id": { "type": "string", "description": "Meta template id." } }, "required": [ "name", "language", "external_id" ] }, "range": { "type": "object", "properties": { "start": { "type": "string", "description": "First UTC day (YYYY-MM-DD), inclusive." }, "end": { "type": "string", "description": "Last UTC day (YYYY-MM-DD), inclusive." } }, "required": [ "start", "end" ] }, "totals": { "type": "object", "properties": { "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "read": { "type": "integer" }, "cost": { "type": "object", "properties": { "amount": { "type": "string", "description": "Decimal string in `currency`." }, "currency": { "type": [ "string", "null" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "sent", "delivered", "read", "cost" ] }, "clicks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Meta button type: `quick_reply_button`, `url_button`, …" }, "button": { "type": "string", "description": "Button text." }, "count": { "type": "integer" } }, "required": [ "type", "button", "count" ] }, "description": "Clicks per button over the range, most-clicked first." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "UTC day." }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "read": { "type": "integer" }, "clicks": { "type": "integer" } }, "required": [ "date", "sent", "delivered", "read", "clicks" ] } }, "fetched_at": { "type": "string", "description": "When Meta was read (cached up to 15 min)." } }, "required": [ "status", "template", "range", "totals", "clicks", "daily", "fetched_at" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "enabling" ] }, "retry_after_seconds": { "type": "integer", "description": "Meta is switching the account’s template insights on; ask again after this." } }, "required": [ "status", "retry_after_seconds" ] } ] }, "CampaignTestSendResult": { "type": "object", "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "header_media_url": { "type": [ "string", "null" ], "description": "WhatsApp: the header media every recipient got." }, "remaining_this_hour": { "type": [ "integer", "null" ], "description": "Test messages this campaign may still send this hour." }, "results": { "type": "array", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "email": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "sent", "failed" ] }, "provider_message_id": { "type": [ "string", "null" ] }, "error_code": { "type": "string", "enum": [ "invalid_phone", "landline", "invalid_email", "duplicate", "opted_out", "contact_blocked", "safety_hold", "missing_variables", "email_not_verified", "send_failed" ] }, "error_message": { "type": "string" }, "provider_code": { "type": [ "string", "null" ] }, "opt_out_reason": { "type": [ "string", "null" ] }, "missing": { "type": "array", "items": { "type": "string" } }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "rendered_text": { "type": [ "string", "null" ] }, "values": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "source": { "type": "string", "enum": [ "variable", "contact_field", "static", "fallback", "example", "empty" ] } }, "required": [ "value", "source" ] } } }, "required": [ "name", "status" ] } } }, "required": [ "campaign_id", "channel", "header_media_url", "remaining_this_hour", "results" ] }, "CampaignTestSendRecipient": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 1, "maxLength": 40 }, "email": { "type": "string", "maxLength": 254, "format": "email" }, "name": { "type": "string", "maxLength": 120 }, "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1000 } } }, "additionalProperties": false }, "CampaignTestSendBody": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignTestSendRecipient" }, "minItems": 1, "maxItems": 5 } }, "required": [ "recipients" ], "additionalProperties": false }, "ClinicWaitlistDemand": { "type": "object", "properties": { "window": { "type": "object", "properties": { "days": { "type": "integer" }, "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "days", "from", "to" ] }, "totals": { "type": "object", "properties": { "waiting_now": { "type": "integer", "description": "Distinct patients with a live entry now (waiting, or holding an offer)." }, "joined": { "type": "integer", "description": "Distinct patients who joined the waitlist inside the window." }, "booked": { "type": "integer", "description": "Distinct patients whose entry became a booking inside the window." } }, "required": [ "waiting_now", "joined", "booked" ] }, "by_specialty": { "type": "array", "items": { "type": "object", "properties": { "specialty": { "type": [ "string", "null" ], "description": "The professional's specialty as the roster spells it; null = «whoever is free» or no specialty on file." }, "label": { "type": "string", "description": "Ready to print: the specialty, «Cualquier profesional» or «Sin especialidad»." }, "waiting_now": { "type": "integer", "description": "Distinct patients with a live entry now (waiting, or holding an offer)." }, "joined": { "type": "integer", "description": "Distinct patients who joined the waitlist inside the window." }, "booked": { "type": "integer", "description": "Distinct patients whose entry became a booking inside the window." }, "professionals": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "waiting_now": { "type": "integer", "description": "Distinct patients with a live entry now (waiting, or holding an offer)." }, "joined": { "type": "integer", "description": "Distinct patients who joined the waitlist inside the window." }, "booked": { "type": "integer", "description": "Distinct patients whose entry became a booking inside the window." } }, "required": [ "professional_id", "name", "waiting_now", "joined", "booked" ] } } }, "required": [ "specialty", "label", "waiting_now", "joined", "booked", "professionals" ] } } }, "required": [ "window", "totals", "by_specialty" ] }, "ClinicProduccionReport": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "professional_id": { "type": [ "string", "null" ], "format": "uuid" }, "basis": { "type": "string", "enum": [ "service_lines", "catalog_price", "mixed", "none", "mirror_lines" ], "description": "Which arm produced the money. `mirror_lines`: a Dentalink / Medilink clinic — the vendor's plan lines marked realizado, by fecha de realización, at the line's total (exact). `service_lines`: the cita's frozen Vitrina lines (a native clinic). `catalog_price`: the catálogo's current price for the prestación a mirrored cita names (an estimate). `mixed`: both. `none`: nothing priced anything." }, "totals": { "type": "object", "properties": { "attended": { "type": [ "integer", "null" ], "description": "Attended citas in the window. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "lines": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "visits": { "type": [ "integer", "null" ], "description": "`mirror_lines` only: distinct visits that produced (patient × day) — what the per-professional `appointments` count, so a table total sums its rows. `null` on the native arms (there `attended` is the total). `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "lines_without_price": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "performed_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "collected_clp": { "type": [ "integer", "null" ], "description": "`payment_allocation.appointment`: money the ledger allocated to these citas. `mirror_payment.received`: every live payment received in the window, by fecha de recepción; `null` with a professional filter (a payment names no professional)." }, "collected_basis": { "type": "string", "enum": [ "payment_allocation.appointment", "mirror_payment.received" ] } }, "required": [ "attended", "lines", "visits", "lines_without_price", "performed_clp", "collected_clp", "collected_basis" ] }, "by_professional": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The professional / prestación id, or the categoría text; `__none__` when the line names none." }, "label": { "type": [ "string", "null" ] }, "appointments": { "type": [ "integer", "null" ], "description": "Citas that produced (`mirror_lines`: visits, patient × day). `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "lines": { "type": [ "integer", "null" ], "description": "Prestaciones performed. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "performed_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "key", "label", "appointments", "lines", "performed_clp" ] }, "description": "Per professional who PERFORMED the work (not who quoted the plan), most CLP first." }, "by_service": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The professional / prestación id, or the categoría text; `__none__` when the line names none." }, "label": { "type": [ "string", "null" ] }, "appointments": { "type": [ "integer", "null" ], "description": "Citas that produced (`mirror_lines`: visits, patient × day). `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "lines": { "type": [ "integer", "null" ], "description": "Prestaciones performed. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "performed_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "key", "label", "appointments", "lines", "performed_clp" ] } }, "by_category": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "The professional / prestación id, or the categoría text; `__none__` when the line names none." }, "label": { "type": [ "string", "null" ] }, "appointments": { "type": [ "integer", "null" ], "description": "Citas that produced (`mirror_lines`: visits, patient × day). `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "lines": { "type": [ "integer", "null" ], "description": "Prestaciones performed. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "performed_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "key", "label", "appointments", "lines", "performed_clp" ] }, "description": "`clinic_service.categoria` is free text: the label is the key." }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`." }, "attended": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "performed_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "collected_clp": { "type": [ "integer", "null" ] } }, "required": [ "month", "attended", "performed_clp", "collected_clp" ] } }, "suppression": { "type": "object", "properties": { "min_count": { "type": "integer" }, "filters_ignored": { "type": "boolean" }, "withheld_rows": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "min_count", "filters_ignored", "withheld_rows" ], "description": "Present only for a caller without `clinic_money:read`." } }, "required": [ "from", "to", "location_id", "professional_id", "basis", "totals", "by_professional", "by_service", "by_category", "months" ] }, "ClinicIngresosReport": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "today": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "timezone": { "type": "string" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "professional_id": { "type": [ "string", "null" ], "format": "uuid" }, "origin": { "type": [ "string", "null" ], "enum": [ "meta", "organic", "unknown" ], "description": "The Origen filter applied; `null` = everyone." }, "state": { "type": "string", "enum": [ "ready", "unavailable" ] }, "state_reason": { "type": [ "string", "null" ] }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mirror", "native", "none" ], "description": "`native`: Vitrina's own agenda and caja (a native clinic). `mirror`: the Dentalink / Medilink revenue mirror. `none`: neither (`state: unavailable`)." }, "synced_at": { "type": [ "string", "null" ] } }, "required": [ "kind", "synced_at" ] }, "rules": { "type": "object", "additionalProperties": { "type": "string" } }, "hoy": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "produccion_clp": { "type": "integer" }, "prestaciones": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "presupuestos": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] }, "pagos": { "type": [ "integer", "null" ] }, "citas": { "type": "integer", "description": "Citas on the agenda today, cancelled ones out. 0 = the clinic is not seeing patients today (closed, holiday), so three $0 figures are not a slow day." } }, "required": [ "day", "produccion_clp", "prestaciones", "presupuestado_clp", "presupuestos", "recaudado_clp", "pagos", "citas" ] }, "totals": { "type": "object", "properties": { "produccion": { "type": "object", "properties": { "total_clp": { "type": "integer" }, "nuevos_clp": { "type": "integer", "description": "Patients whose primera visita (Nuevo / Nuevo · reagenda) starts in the same month." }, "tratamiento_clp": { "type": "integer" }, "prestaciones": { "type": "integer" } }, "required": [ "total_clp", "nuevos_clp", "tratamiento_clp", "prestaciones" ] }, "presupuestado": { "type": "object", "properties": { "total_clp": { "type": "integer" }, "nuevos_clp": { "type": "integer", "description": "Patients whose primera visita (Nuevo / Nuevo · reagenda) starts in the same month." }, "tratamiento_clp": { "type": "integer" }, "presupuestos": { "type": "integer" } }, "required": [ "total_clp", "nuevos_clp", "tratamiento_clp", "presupuestos" ] }, "recaudacion": { "type": [ "object", "null" ], "properties": { "total_clp": { "type": "integer" }, "nuevos_clp": { "type": "integer", "description": "Patients whose primera visita (Nuevo / Nuevo · reagenda) starts in the same month." }, "tratamiento_clp": { "type": "integer" }, "pagos": { "type": "integer" } }, "required": [ "total_clp", "nuevos_clp", "tratamiento_clp", "pagos" ], "description": "`null` with `professional_id`: a payment names no professional." }, "by_origen": { "type": [ "object", "null" ], "properties": { "meta": { "type": "object", "properties": { "produccion_clp": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] } }, "required": [ "produccion_clp", "presupuestado_clp", "recaudado_clp" ] }, "organic": { "type": "object", "properties": { "produccion_clp": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] } }, "required": [ "produccion_clp", "presupuestado_clp", "recaudado_clp" ] }, "unknown": { "type": "object", "properties": { "produccion_clp": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] } }, "required": [ "produccion_clp", "presupuestado_clp", "recaudado_clp" ] } }, "description": "Producción, presupuestado and recaudación by Origen (D77): `meta`, `organic`, `unknown` («Sin dato»). `recaudado_clp` is `null` with `professional_id`. The whole object is `null` when the Origen could not be read (never guessed as `unknown`)." } }, "required": [ "produccion", "presupuestado", "recaudacion", "by_origen" ] }, "days": { "type": "array", "items": { "type": "object", "properties": { "produccion": { "type": "object", "properties": { "total_clp": { "type": "integer" }, "nuevos_clp": { "type": "integer", "description": "Patients whose primera visita (Nuevo / Nuevo · reagenda) starts in the same month." }, "tratamiento_clp": { "type": "integer" }, "prestaciones": { "type": "integer" } }, "required": [ "total_clp", "nuevos_clp", "tratamiento_clp", "prestaciones" ] }, "presupuestado": { "type": "object", "properties": { "total_clp": { "type": "integer" }, "nuevos_clp": { "type": "integer", "description": "Patients whose primera visita (Nuevo / Nuevo · reagenda) starts in the same month." }, "tratamiento_clp": { "type": "integer" }, "presupuestos": { "type": "integer" } }, "required": [ "total_clp", "nuevos_clp", "tratamiento_clp", "presupuestos" ] }, "recaudacion": { "type": [ "object", "null" ], "properties": { "total_clp": { "type": "integer" }, "nuevos_clp": { "type": "integer", "description": "Patients whose primera visita (Nuevo / Nuevo · reagenda) starts in the same month." }, "tratamiento_clp": { "type": "integer" }, "pagos": { "type": "integer" } }, "required": [ "total_clp", "nuevos_clp", "tratamiento_clp", "pagos" ], "description": "`null` with `professional_id`: a payment names no professional." }, "by_origen": { "type": [ "object", "null" ], "properties": { "meta": { "type": "object", "properties": { "produccion_clp": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] } }, "required": [ "produccion_clp", "presupuestado_clp", "recaudado_clp" ] }, "organic": { "type": "object", "properties": { "produccion_clp": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] } }, "required": [ "produccion_clp", "presupuestado_clp", "recaudado_clp" ] }, "unknown": { "type": "object", "properties": { "produccion_clp": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "recaudado_clp": { "type": [ "integer", "null" ] } }, "required": [ "produccion_clp", "presupuestado_clp", "recaudado_clp" ] } }, "description": "Producción, presupuestado and recaudación by Origen (D77): `meta`, `organic`, `unknown` («Sin dato»). `recaudado_clp` is `null` with `professional_id`. The whole object is `null` when the Origen could not be read (never guessed as `unknown`)." }, "day": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" } }, "required": [ "produccion", "presupuestado", "recaudacion", "by_origen", "day" ] } }, "clinic": { "type": "object", "properties": { "produccion_clp": { "type": "integer", "description": "Performed by this doctor (the performer)." }, "prestaciones": { "type": "integer" }, "presupuestos": { "type": "integer", "description": "Real presupuestos issued ($0 and evaluación-only out), by the quoting doctor." }, "presupuestado_clp": { "type": "integer", "description": "Their value without evaluación lines." }, "aceptados": { "type": "integer" }, "aceptacion_pct": { "type": [ "number", "null" ] }, "aceptado_clp": { "type": "integer" }, "abonado_clp": { "type": "integer", "description": "Already paid on the plans issued in the period." }, "nuevos_presentados": { "type": "integer" }, "nuevos_aceptados": { "type": "integer" } }, "required": [ "produccion_clp", "prestaciones", "presupuestos", "presupuestado_clp", "aceptados", "aceptacion_pct", "aceptado_clp", "abonado_clp", "nuevos_presentados", "nuevos_aceptados" ] }, "by_professional": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": "string", "format": "uuid" }, "professional_name": { "type": "string" }, "produccion_clp": { "type": "integer", "description": "Performed by this doctor (the performer)." }, "prestaciones": { "type": "integer" }, "presupuestos": { "type": "integer", "description": "Real presupuestos issued ($0 and evaluación-only out), by the quoting doctor." }, "presupuestado_clp": { "type": "integer", "description": "Their value without evaluación lines." }, "aceptados": { "type": "integer" }, "aceptacion_pct": { "type": [ "number", "null" ] }, "aceptado_clp": { "type": "integer" }, "abonado_clp": { "type": "integer", "description": "Already paid on the plans issued in the period." }, "nuevos_presentados": { "type": "integer" }, "nuevos_aceptados": { "type": "integer" } }, "required": [ "professional_id", "professional_name", "produccion_clp", "prestaciones", "presupuestos", "presupuestado_clp", "aceptados", "aceptacion_pct", "aceptado_clp", "abonado_clp", "nuevos_presentados", "nuevos_aceptados" ] } } }, "required": [ "from", "to", "today", "timezone", "location_id", "professional_id", "origin", "state", "state_reason", "source", "rules", "hoy", "totals", "days", "clinic", "by_professional" ] }, "ClinicIngresosMonths": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "state": { "type": "string", "enum": [ "ready", "unavailable" ] }, "rules": { "type": "object", "additionalProperties": { "type": "string" } }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`." }, "produccion_clp": { "type": "integer" }, "presupuestos": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "aceptacion_pct": { "type": [ "number", "null" ] }, "aceptado_clp": { "type": "integer" }, "recaudacion_clp": { "type": "integer" } }, "required": [ "month", "produccion_clp", "presupuestos", "presupuestado_clp", "aceptacion_pct", "aceptado_clp", "recaudacion_clp" ] } }, "professionals": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": "string", "format": "uuid" }, "professional_name": { "type": "string" }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "`YYYY-MM`." }, "produccion_clp": { "type": "integer" }, "presupuestos": { "type": "integer" }, "presupuestado_clp": { "type": "integer" }, "aceptacion_pct": { "type": [ "number", "null" ] }, "aceptado_clp": { "type": "integer" } }, "required": [ "month", "produccion_clp", "presupuestos", "presupuestado_clp", "aceptacion_pct", "aceptado_clp" ] } } }, "required": [ "professional_id", "professional_name", "months" ] } } }, "required": [ "from", "to", "state", "rules", "months", "professionals" ] }, "ClinicIngresosDay": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "identity": { "type": "boolean" }, "plans": { "type": "array", "items": { "type": "object", "properties": { "plan_id": { "type": "string", "format": "uuid" }, "patient": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "description": "`name` only for a caller allowed to see patient identity (`contacts:read` + `clinic:read`, plus `clinic_patients:read` for an API credential). A caller on `clinic_insights:read` alone gets `id` and `name` both `null`." }, "professional_id": { "type": [ "string", "null" ], "format": "uuid" }, "professional_name": { "type": [ "string", "null" ] }, "total_clp": { "type": "integer" }, "abonado_clp": { "type": "integer" }, "deuda_clp": { "type": "integer" }, "tipo": { "type": "string", "enum": [ "nuevo", "tratamiento" ] }, "origen": { "type": [ "string", "null" ], "enum": [ "meta", "organic", "unknown" ] }, "aceptado": { "type": [ "boolean", "null" ], "description": "Números comerciales' verdict; `null` for a $0 or evaluación-only plan." } }, "required": [ "plan_id", "patient", "professional_id", "professional_name", "total_clp", "abonado_clp", "deuda_clp", "tipo", "origen", "aceptado" ] } }, "payments": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string", "format": "uuid" }, "time": { "type": [ "string", "null" ] }, "patient": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "description": "`name` only for a caller allowed to see patient identity (`contacts:read` + `clinic:read`, plus `clinic_patients:read` for an API credential). A caller on `clinic_insights:read` alone gets `id` and `name` both `null`." }, "amount_clp": { "type": "integer" }, "tipo": { "type": "string", "enum": [ "nuevo", "tratamiento" ] }, "origen": { "type": [ "string", "null" ], "enum": [ "meta", "organic", "unknown" ] } }, "required": [ "payment_id", "time", "patient", "amount_clp", "tipo", "origen" ] } }, "produccion": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": [ "string", "null" ], "format": "uuid" }, "professional_name": { "type": [ "string", "null" ] }, "prestaciones": { "type": "integer" }, "produccion_clp": { "type": "integer" } }, "required": [ "professional_id", "professional_name", "prestaciones", "produccion_clp" ] } } }, "required": [ "day", "identity", "plans", "payments", "produccion" ] }, "AgendaResults": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "timezone": { "type": "string" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "family": { "type": "string", "enum": [ "clinic", "dealer", "generic" ], "description": "Vocabulary: citas/pacientes, visitas/clientes, citas/clientes." }, "previous_period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" } }, "required": [ "from", "to" ] }, "bookings": { "type": "object", "properties": { "ai": { "type": "integer", "description": "Citas of the period booked by Vitrina's agent in a conversation (`source='agent'`, not a public booking page)." }, "agenda_total": { "type": "integer", "description": "Every cita of the period (blocks and holds excluded)." }, "share_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "ai_attended": { "type": "integer", "description": "Of `ai`: citas the patient attended." }, "ai_missed": { "type": "integer", "description": "Of `ai`: cancelled (with or without notice) or no-show." }, "ai_upcoming": { "type": "integer", "description": "Agent-booked citas dated after `to` — booked, not happened yet. Not part of `ai`." }, "first_ai_booked_on": { "type": [ "string", "null" ], "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "description": "Day (clinic zone) the agent booked its first cita ever. A window that starts earlier has no agent bookings before this day." }, "previous": { "type": "object", "properties": { "ai": { "type": "integer" }, "agenda_total": { "type": "integer" }, "share_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." } }, "required": [ "ai", "agenda_total", "share_pct" ] }, "rule": { "type": "string" } }, "required": [ "ai", "agenda_total", "share_pct", "ai_attended", "ai_missed", "ai_upcoming", "first_ai_booked_on", "previous", "rule" ] }, "conversation_rate": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "measured", "not_booking_yet", "unavailable" ], "description": "`not_booking_yet`: the agent had not booked any cita by `to`; `unavailable`: the read failed. Both leave every figure `null`." }, "from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "description": "First day actually measured: the page `from`, or the day Vitrina first booked when that is later." }, "to": { "type": [ "string", "null" ], "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "starts_at_first_booking": { "type": "boolean", "description": "True when `from` was moved forward to the first AI booking (conversations before it could not be booked by the AI)." }, "conversations": { "type": [ "integer", "null" ], "description": "Denominator — conversations Vitrina answered ALONE in the window with NEW people (they had not written before the window — D94; the others are in `existing`): the person wrote, the AI agent replied after that message, and no team member (`human_user`) wrote before the AI booking (or in the whole window, with no booking). Tool calls, reasoning and events are not replies; an AI follow-up nobody answered is not counted. Quarantined conversations, system senders and team accounts are out. Every sucursal (conversations carry no location)." }, "booked_conversations": { "type": [ "integer", "null" ], "description": "Numerator — of `conversations`, those where the agent booked at least one cita (`source=agent`, not a public booking page; blocks, holds and anuladas out) BOOKED inside the window." }, "ai_bookings": { "type": [ "integer", "null" ], "description": "Citas the agent booked in those conversations (a conversation may book more than one). Counted by the day they were booked, unlike `bookings.ai` (by the day of the cita)." }, "rate_pct": { "type": [ "number", "null" ], "description": "`booked_conversations ÷ conversations`, percent with one decimal." }, "team_helped": { "type": [ "integer", "null" ], "description": "Conversations the AI answered where a team member wrote before the outcome — excluded from the rate." }, "existing": { "type": [ "object", "null" ], "properties": { "conversations": { "type": "integer", "description": "Conversations Vitrina answered alone with people who had written to the business BEFORE the window (patients’ follow-ups, changes of hour, earlier leads)." }, "booked_conversations": { "type": "integer", "description": "Of them, those where the agent booked at least one cita (anuladas excluded)." }, "ai_bookings": { "type": "integer", "description": "Citas the agent booked in them." } }, "required": [ "conversations", "booked_conversations", "ai_bookings" ], "description": "D94: conversations of people who had written to the business BEFORE the window (follow-ups, changes of hour) — outside the rate, said on their own line. `null` when not measured." }, "cancelled": { "type": [ "integer", "null" ], "description": "Citas the agent booked for new people in the window that were then anuladas — never in `ai_bookings`. `null` when not measured." }, "truncated": { "type": "boolean", "description": "The read hit its row cap: counts are a floor." }, "previous": { "type": [ "object", "null" ], "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "conversations": { "type": "integer" }, "booked_conversations": { "type": "integer" }, "rate_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." } }, "required": [ "from", "to", "conversations", "booked_conversations", "rate_pct" ], "description": "The equal-length window right before, only when the AI was already booking through all of it; `null` otherwise (no fair baseline)." }, "rule": { "type": "string" } }, "required": [ "state", "from", "to", "starts_at_first_booking", "conversations", "booked_conversations", "ai_bookings", "rate_pct", "team_helped", "existing", "cancelled", "truncated", "previous", "rule" ], "description": "The AI booking rate BY CONVERSATION (vitrina-app#3711), beside the agenda-based `bookings.share_pct`: of the conversations Vitrina answered on its own, the share where it booked a cita." }, "money": { "type": "object", "properties": { "applies": { "type": "boolean", "description": "False for a vertical with no priced citas." }, "withheld": { "type": "boolean" }, "booked_clp": { "type": [ "integer", "null" ], "description": "Value of the AI-booked citas whose value is known (pipeline, not cash)." }, "booked_priced": { "type": "integer" }, "booked_unpriced": { "type": "integer", "description": "AI-booked citas with no price — «sin dato»." }, "agenda_clp": { "type": [ "integer", "null" ], "description": "CLP. `null` when unknown or when the caller lacks `clinic_money:read` (`money.withheld`)." }, "clp_share_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "paid_clp": { "type": [ "integer", "null" ], "description": "Cash received in the period by the patients Vitrina booked, from the day it booked them." }, "paid_patients": { "type": [ "integer", "null" ] }, "unlinked": { "type": "integer", "description": "AI-booked citas with no patient to match a payment to." }, "regime": { "type": [ "string", "null" ], "enum": [ "mirror", "native" ] }, "previous": { "type": "object", "properties": { "booked_clp": { "type": [ "integer", "null" ], "description": "CLP. `null` when unknown or when the caller lacks `clinic_money:read` (`money.withheld`)." }, "paid_clp": { "type": [ "integer", "null" ], "description": "CLP. `null` when unknown or when the caller lacks `clinic_money:read` (`money.withheld`)." } }, "required": [ "booked_clp", "paid_clp" ] }, "rule_booked": { "type": "string" }, "rule_paid": { "type": "string" } }, "required": [ "applies", "withheld", "booked_clp", "booked_priced", "booked_unpriced", "agenda_clp", "clp_share_pct", "paid_clp", "paid_patients", "unlinked", "regime", "previous", "rule_booked", "rule_paid" ] }, "out_of_hours": { "type": "object", "properties": { "configured": { "type": "boolean", "description": "False when the workspace has no business hours; count/pct are then null." }, "count": { "type": [ "integer", "null" ] }, "pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "previous_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "heatmap": { "type": "array", "items": { "type": "object", "properties": { "weekday": { "type": "integer", "minimum": 1, "maximum": 7, "description": "1 = Monday … 7 = Sunday." }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "count": { "type": "integer" } }, "required": [ "weekday", "hour", "count" ] }, "description": "AI bookings by weekday × hour of the booking, in `timezone`. Empty cells omitted." }, "rule": { "type": "string" } }, "required": [ "configured", "count", "pct", "previous_pct", "heatmap", "rule" ] }, "autonomy": { "type": "object", "properties": { "no_human": { "type": "integer" }, "pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "measured": { "type": "integer" }, "unknown": { "type": "integer" }, "previous_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "rule": { "type": "string" } }, "required": [ "no_human", "pct", "measured", "unknown", "previous_pct", "rule" ] }, "time_to_book": { "type": "object", "properties": { "median_seconds": { "type": [ "integer", "null" ] }, "p95_seconds": { "type": [ "integer", "null" ] }, "p95_phrase": { "type": [ "string", "null" ] }, "measured": { "type": "integer" }, "unknown": { "type": "integer" }, "previous_median_seconds": { "type": [ "integer", "null" ] }, "rule": { "type": "string" } }, "required": [ "median_seconds", "p95_seconds", "p95_phrase", "measured", "unknown", "previous_median_seconds", "rule" ] }, "hours_returned": { "type": "object", "properties": { "minutes_per_booking": { "type": "integer" }, "hours": { "type": "number" }, "rule": { "type": "string" } }, "required": [ "minutes_per_booking", "hours", "rule" ] }, "recovery": { "type": "object", "properties": { "window_days": { "type": "integer" }, "known_attendance": { "type": "integer" }, "unknown_attendance": { "type": "integer" }, "no_show_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "no_show": { "type": "object", "properties": { "count": { "type": "integer" }, "recovered": { "type": "integer" }, "recovered_via_vitrina": { "type": "integer" }, "recovered_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "via_vitrina_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "pending": { "type": "integer", "description": "Not recovered yet, still inside the 30 days." }, "unlinked": { "type": "integer", "description": "Missed with no identifiable patient." } }, "required": [ "count", "recovered", "recovered_via_vitrina", "recovered_pct", "via_vitrina_pct", "pending", "unlinked" ] }, "cancelled": { "type": "object", "properties": { "count": { "type": "integer" }, "recovered": { "type": "integer" }, "recovered_via_vitrina": { "type": "integer" }, "recovered_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "via_vitrina_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "pending": { "type": "integer", "description": "Not recovered yet, still inside the 30 days." }, "unlinked": { "type": "integer", "description": "Missed with no identifiable patient." } }, "required": [ "count", "recovered", "recovered_via_vitrina", "recovered_pct", "via_vitrina_pct", "pending", "unlinked" ] }, "rule_no_show": { "type": "string" }, "rule_recovered": { "type": "string" } }, "required": [ "window_days", "known_attendance", "unknown_attendance", "no_show_pct", "no_show", "cancelled", "rule_no_show", "rule_recovered" ] }, "confirmation": { "type": "object", "properties": { "applies": { "type": "boolean" }, "confirmed_attendance_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "unconfirmed_attendance_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "confirmed_closed": { "type": [ "integer", "null" ] }, "unconfirmed_closed": { "type": [ "integer", "null" ] }, "rule": { "type": "string" } }, "required": [ "applies", "confirmed_attendance_pct", "unconfirmed_attendance_pct", "confirmed_closed", "unconfirmed_closed", "rule" ] }, "ads": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "active", "not_active", "unavailable" ] }, "spend_clp": { "type": [ "number", "null" ] }, "booked": { "type": [ "integer", "null" ] }, "attended": { "type": [ "integer", "null" ] }, "paid": { "type": [ "integer", "null" ] }, "cost_per_booked": { "type": [ "integer", "null" ] }, "cost_per_attended": { "type": [ "integer", "null" ] }, "cost_per_paid": { "type": [ "integer", "null" ] }, "rule": { "type": "string" } }, "required": [ "state", "spend_clp", "booked", "attended", "paid", "cost_per_booked", "cost_per_attended", "cost_per_paid", "rule" ] }, "reminders": { "type": "object", "properties": { "applies": { "type": "boolean" }, "sent": { "type": "integer" }, "failed": { "type": "integer" }, "failed_pct": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` — never 0 — with no denominator." }, "by_cause": { "type": "array", "items": { "type": "object", "properties": { "cause": { "type": "string", "enum": [ "no_patient_link", "no_phone", "no_channel", "opted_out", "template_not_approved", "meta_payment_block", "no_whatsapp", "window_closed", "template_rejected", "send_error" ] }, "count": { "type": "integer" } }, "required": [ "cause", "count" ] } }, "rule": { "type": "string" } }, "required": [ "applies", "sent", "failed", "failed_pct", "by_cause", "rule" ] }, "truncated": { "type": "boolean" } }, "required": [ "from", "to", "timezone", "location_id", "family", "previous_period", "bookings", "conversation_rate", "money", "out_of_hours", "autonomy", "time_to_book", "hours_returned", "recovery", "confirmation", "ads", "reminders", "truncated" ] }, "AgendaResultsPeople": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ai_bookings", "out_of_hours", "paid_patients" ] }, "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "count": { "type": [ "integer", "null" ], "description": "The number on the page, by construction (one read): `bookings.ai`, `out_of_hours.count` or `money.paid_patients`. `null` = not measured (no schedule; money withheld or nobody linked)." }, "people": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "patient_link": { "type": "string", "enum": [ "linked", "none", "unknown" ] }, "patient": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "rut": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id" ], "description": "The roster patient — same shape and identity gate as `/ads/attributed-sales` (`AdsLinkedPatient`): `name` / `rut` / `phone` need `contacts:read` + `clinic:read` (plus `clinic_patients:read` for an API credential)." }, "contact": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "key": { "type": "string" } }, "required": [ "id", "display_name", "key" ] }, "cita": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_id": { "type": [ "string", "null" ] }, "starts_at": { "type": "string", "description": "When the cita happens (ISO)." }, "booked_at": { "type": "string", "description": "When the assistant booked it (ISO)." }, "status": { "type": "string" }, "professional": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "out_of_hours": { "type": [ "boolean", "null" ], "description": "Booked while closed; `null` when no business hours are set." } }, "required": [ "id", "display_id", "starts_at", "booked_at", "status", "professional", "out_of_hours" ], "description": "The cita (`ai_bookings` / `out_of_hours`); for `paid_patients`, their first AI-booked cita of the window." }, "paid": { "type": [ "object", "null" ], "properties": { "total": { "type": "number", "description": "CLP." }, "count": { "type": "integer" }, "since_day": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$", "description": "The day Vitrina first booked them; payments count from it." }, "payments": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "amount": { "type": "number" } }, "required": [ "day", "amount" ] } } }, "required": [ "total", "count", "since_day", "payments" ], "description": "`paid_patients` only." } }, "required": [ "key", "patient_link", "patient", "contact", "cita", "paid" ] }, "description": "Exactly `count` rows (citas by start; payers by total)." }, "truncated": { "type": "boolean", "description": "The window read hit its row cap, as the page’s own." }, "withheld": { "type": "boolean", "description": "`paid_patients` without `clinic_money:read`: no list." }, "people_state": { "type": "string", "enum": [ "ready", "unavailable" ] } }, "required": [ "metric", "from", "to", "location_id", "count", "people", "truncated", "withheld", "people_state" ] }, "ClinicComercialReport": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "timezone": { "type": "string" }, "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "professional_id": { "type": [ "string", "null" ], "format": "uuid" }, "state": { "type": "string", "enum": [ "ready", "settling", "empty" ] }, "state_reason": { "type": [ "string", "null" ] }, "regime": { "type": "string", "enum": [ "evidencia", "explicita" ] }, "regime_label": { "type": "string" }, "regime_rule": { "type": "string" }, "source": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "mirror", "native" ] }, "synced_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "kind", "synced_at" ] }, "formulas": { "type": "object", "properties": { "acceptance": { "type": "string", "enum": [ "mentores_2026_09_25" ] }, "cierre": { "type": "string", "enum": [ "cierre_2026_09_25" ] }, "first_visit": { "type": "string", "enum": [ "propuesta", "mentores_2026_09_29" ] }, "second_visit": { "type": "string", "enum": [ "propuesta", "mentores_2026_09_29" ] }, "botados": { "type": "string", "enum": [ "propuesta", "mentores_2026_09_29" ] } }, "required": [ "acceptance", "cierre", "first_visit", "second_visit", "botados" ] }, "headline": { "type": "object", "properties": { "collected_clp": { "type": [ "integer", "null" ], "description": "Cash collected in the window. `null` with a professional filter: a payment has no professional." }, "previous_collected_clp": { "type": [ "integer", "null" ] }, "delta_pct": { "type": [ "number", "null" ] }, "previous_from": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "previous_to": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$" }, "rule": { "type": "string" } }, "required": [ "collected_clp", "previous_collected_clp", "delta_pct", "previous_from", "previous_to", "rule" ] }, "acceptance": { "type": "object", "properties": { "presented": { "type": [ "integer", "null" ], "description": "Presupuestos presented (issued), one per lineage. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "same_day": { "type": [ "integer", "null" ], "description": "Accepted the day they were issued. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "later": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "cita_only": { "type": [ "integer", "null" ], "description": "Accepted only through a cita not attended — still ahead, or cancelled / missed after it was booked. The acceptance stays (counted at the moment, not taken back); this is the risk the owner sees. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "pending": { "type": [ "integer", "null" ], "description": "Not accepted yet, window still open. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "presented_clp": { "type": [ "integer", "null" ], "description": "CLP presented, entry lines excluded. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate_30d": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "rate_60d": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "formula": { "type": "string", "enum": [ "mentores_2026_09_25" ] }, "window_days": { "type": "integer" }, "long_window_days": { "type": "integer" }, "rule": { "type": "string" }, "reference": { "type": [ "object", "null" ], "properties": { "label": { "type": "string", "description": "«Rango de referencia del programa»." }, "especialidad": { "type": [ "string", "null" ], "enum": [ "implantologia", "ortodoncia", "estetica" ], "description": "The especialidad whose range applies; `null` = the general range." }, "band": { "type": [ "string", "null" ], "enum": [ "muy_malo", "malo", "regular", "bueno", "excelente" ], "description": "Where the rate falls; `null` when the rate is `null`." }, "note": { "type": [ "string", "null" ], "description": "At `excelente`: «A este nivel conviene revisar tus precios.»" }, "muy_malo_upper_pct": { "type": [ "number", "null" ] }, "malo_upper_pct": { "type": "number" }, "regular_upper_pct": { "type": "number" }, "excelente_lower_pct": { "type": [ "number", "null" ] } }, "required": [ "label", "especialidad", "band", "note", "muy_malo_upper_pct", "malo_upper_pct", "regular_upper_pct", "excelente_lower_pct" ], "description": "The ODM mentors' reference band for this acceptance rate (#2464): below `muy_malo_upper_pct` muy malo, below `malo_upper_pct` malo, below `regular_upper_pct` regular, above `excelente_lower_pct` excelente, bueno otherwise. A dentist reads their especialidad's range when one exists, else the general one. `null` when no range exists — never an invented band." } }, "required": [ "presented", "accepted", "rate", "same_day", "later", "cita_only", "pending", "presented_clp", "accepted_clp", "rate_30d", "rate_60d", "formula", "window_days", "long_window_days", "rule", "reference" ] }, "cierres": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "value_clp": { "type": [ "integer", "null" ], "description": "The accepted value of the presupuestos that closed — never the payments. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted_without_payment": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "formula": { "type": "string", "enum": [ "cierre_2026_09_25" ] }, "rule": { "type": "string" } }, "required": [ "count", "value_clp", "accepted_without_payment", "formula", "rule" ] }, "cohorts": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string", "description": "Issue month, `YYYY-MM`." }, "presented": { "type": [ "integer", "null" ], "description": "Presupuestos presented (issued), one per lineage. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "same_day": { "type": [ "integer", "null" ], "description": "Accepted the day they were issued. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "later": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "cita_only": { "type": [ "integer", "null" ], "description": "Accepted only through a cita not attended — still ahead, or cancelled / missed after it was booked. The acceptance stays (counted at the moment, not taken back); this is the risk the owner sees. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "pending": { "type": [ "integer", "null" ], "description": "Not accepted yet, window still open. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "presented_clp": { "type": [ "integer", "null" ], "description": "CLP presented, entry lines excluded. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate_30d": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "rate_60d": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "mature": { "type": "boolean", "description": "Every presupuesto of the month is past its window." } }, "required": [ "month", "presented", "accepted", "rate", "same_day", "later", "cita_only", "pending", "presented_clp", "accepted_clp", "rate_30d", "rate_60d", "mature" ] } }, "by_professional": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": "string", "format": "uuid" }, "professional_name": { "type": "string" }, "presented": { "type": [ "integer", "null" ], "description": "Presupuestos presented (issued), one per lineage. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "same_day": { "type": [ "integer", "null" ], "description": "Accepted the day they were issued. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "later": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "cita_only": { "type": [ "integer", "null" ], "description": "Accepted only through a cita not attended — still ahead, or cancelled / missed after it was booked. The acceptance stays (counted at the moment, not taken back); this is the risk the owner sees. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "pending": { "type": [ "integer", "null" ], "description": "Not accepted yet, window still open. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "presented_clp": { "type": [ "integer", "null" ], "description": "CLP presented, entry lines excluded. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "accepted_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "cierres": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "cierres_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "reference": { "type": [ "object", "null" ], "properties": { "label": { "type": "string", "description": "«Rango de referencia del programa»." }, "especialidad": { "type": [ "string", "null" ], "enum": [ "implantologia", "ortodoncia", "estetica" ], "description": "The especialidad whose range applies; `null` = the general range." }, "band": { "type": [ "string", "null" ], "enum": [ "muy_malo", "malo", "regular", "bueno", "excelente" ], "description": "Where the rate falls; `null` when the rate is `null`." }, "note": { "type": [ "string", "null" ], "description": "At `excelente`: «A este nivel conviene revisar tus precios.»" }, "muy_malo_upper_pct": { "type": [ "number", "null" ] }, "malo_upper_pct": { "type": "number" }, "regular_upper_pct": { "type": "number" }, "excelente_lower_pct": { "type": [ "number", "null" ] } }, "required": [ "label", "especialidad", "band", "note", "muy_malo_upper_pct", "malo_upper_pct", "regular_upper_pct", "excelente_lower_pct" ], "description": "The ODM mentors' reference band for this acceptance rate (#2464): below `muy_malo_upper_pct` muy malo, below `malo_upper_pct` malo, below `regular_upper_pct` regular, above `excelente_lower_pct` excelente, bueno otherwise. A dentist reads their especialidad's range when one exists, else the general one. `null` when no range exists — never an invented band." } }, "required": [ "professional_id", "professional_name", "presented", "accepted", "rate", "same_day", "later", "cita_only", "pending", "presented_clp", "accepted_clp", "cierres", "cierres_clp", "reference" ] } }, "unassigned_presented": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "unassigned_cierres": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "accepted_clp": { "type": [ "integer", "null" ], "description": "`null` for a caller without `clinic_money:read`: month rows then carry only the cash." }, "produced_clp": { "type": [ "integer", "null" ], "description": "`null` for a caller without `clinic_money:read`: month rows then carry only the cash." }, "collected_clp": { "type": [ "integer", "null" ] }, "cierres": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "cierres_clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "month", "accepted_clp", "produced_clp", "collected_clp", "cierres", "cierres_clp" ] } }, "first_visit": { "type": "object", "properties": { "formula": { "type": "string", "enum": [ "propuesta", "mentores_2026_09_29" ] }, "patients": { "type": [ "integer", "null" ], "description": "New patients whose first-ever attended cita falls in the window. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "paid": { "type": [ "integer", "null" ], "description": "Of them, the ones who paid MORE than the evaluación that day. `null` also when the clinic has no priced evaluación (`reason`). `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "evaluation_price_clp": { "type": [ "integer", "null" ], "description": "The clinic's evaluación price the day's payments are compared to (the highest priced evaluación prestación). `null` = none priced." }, "reason": { "type": [ "string", "null" ], "description": "Why `rate` is `null` when patients exist (no priced evaluación)." }, "rule": { "type": "string" } }, "required": [ "formula", "patients", "paid", "rate", "evaluation_price_clp", "reason", "rule" ] }, "second_visit": { "type": "object", "properties": { "formula": { "type": "string", "enum": [ "propuesta", "mentores_2026_09_29" ] }, "eligible": { "type": [ "integer", "null" ], "description": "Accepted presupuestos of the cohort. `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "converted": { "type": [ "integer", "null" ], "description": "Of them, accepted after the issue day («capturado en una visita posterior»). `null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "rate": { "type": [ "number", "null" ], "description": "Percent, one decimal. `null` when there was nothing to divide — never 0 — or, for a caller without `clinic_money:read`, when it rests on fewer than 5 cases." }, "rule": { "type": "string" } }, "required": [ "formula", "eligible", "converted", "rate", "rule" ] }, "botados": { "type": "object", "properties": { "unaccepted": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "count", "clp" ], "description": "«Nunca aceptó»: nothing performed, no cita and no pago in the 90 days since issue, no future cita. CLP = the presupuesto." }, "accepted_unscheduled": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "count", "clp" ], "description": "Always empty since `mentores_2026_09_29`: an accepted presupuesto has a performed line or a booked cita. Kept so the contract only grew." }, "mid_treatment_no_future_cita": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "count", "clp" ], "description": "«Quedó a medias»: something performed, value left, no cita and no pago in the last 90 days, no future cita. CLP = what is left unperformed." }, "by_professional": { "type": "array", "items": { "type": "object", "properties": { "professional_id": { "type": "string", "format": "uuid" }, "professional_name": { "type": "string" }, "unaccepted": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "count", "clp" ] }, "mid_treatment_no_future_cita": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "count", "clp" ] } }, "required": [ "professional_id", "professional_name", "unaccepted", "mid_treatment_no_future_cita" ] }, "description": "Both lists per ISSUING professional, most CLP first. Empty for a caller without `clinic_money:read`." }, "formula": { "type": "string", "enum": [ "propuesta", "mentores_2026_09_29" ] }, "basis": { "type": "string", "enum": [ "live_last_6_months", "live_last_12_months" ], "description": "A live snapshot over the presupuestos issued in the last 12 months (`live_last_6_months` is no longer emitted)." }, "idle_days": { "type": "integer", "description": "Days without cita or pago that make a presupuesto botado (90)." }, "total": { "type": "object", "properties": { "count": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "clp": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "count", "clp" ] }, "focus": { "type": [ "string", "null" ], "enum": [ "unaccepted", "accepted_unscheduled", "mid_treatment_no_future_cita" ] }, "rule": { "type": "string" } }, "required": [ "unaccepted", "accepted_unscheduled", "mid_treatment_no_future_cita", "by_professional", "formula", "basis", "idle_days", "total", "focus", "rule" ] }, "coverage": { "type": "object", "properties": { "plans_without_lines": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "excluded_zero": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." }, "excluded_entry_only": { "type": [ "integer", "null" ], "description": "`null` only for a caller without `clinic_money:read`, when it rests on 1–4 cases." } }, "required": [ "plans_without_lines", "excluded_zero", "excluded_entry_only" ] }, "suppression": { "type": "object", "properties": { "min_count": { "type": "integer" }, "professionals_withheld": { "type": "integer" }, "filters_ignored": { "type": "boolean", "description": "The Consultor view always reads the last 3 closed calendar months (the report's `from`/`to`) and ignores the requested range and professional / sucursal filters." } }, "required": [ "min_count", "professionals_withheld" ] } }, "required": [ "from", "to", "timezone", "location_id", "professional_id", "state", "state_reason", "regime", "regime_label", "regime_rule", "source", "formulas", "headline", "acceptance", "cierres", "cohorts", "by_professional", "unassigned_presented", "unassigned_cierres", "months", "first_visit", "second_visit", "botados", "coverage" ] }, "AdsState": { "type": "object", "properties": { "entitlement": { "type": "string", "enum": [ "off", "pending_on", "on", "pending_off" ] }, "needs_remint": { "type": "boolean", "description": "True when the live key is the wrong kind for the entitlement: ON with a core key, or OFF with an Ads key." }, "key_kind": { "type": "string", "enum": [ "core", "ads" ] }, "grant_scopes": { "type": "array", "items": { "type": "string" } }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "entitlement", "needs_remint", "key_kind", "grant_scopes", "last_error" ] }, "AdsConversionSyncCatalog": { "type": "object", "properties": {} }, "AdsMetaPixel": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "last_fired_at": { "type": [ "string", "null" ] }, "is_unavailable": { "type": "boolean" } }, "required": [ "id" ] }, "AdsExportDestinations": { "type": "object", "properties": { "privacy_mode": { "type": "string" }, "export_meta_enabled": { "type": "boolean" }, "export_google_enabled": { "type": "boolean" }, "destinations": { "type": "array", "items": { "type": "object", "properties": {} } } }, "required": [ "privacy_mode", "export_meta_enabled", "export_google_enabled", "destinations" ] }, "AdsPrivacyCheck": { "type": "object", "properties": { "required": { "type": [ "string", "null" ], "enum": [ "platform_safe" ] }, "actual": { "type": "string" }, "applied": { "type": "boolean" } }, "required": [ "required", "actual", "applied" ] }, "AdsDestinationResult": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "created", "updated", "enabled", "unchanged" ], "description": "`enabled` = a destination already sent to this dataset and was switched back on; `unchanged` = it already sent there, enabled; nothing was written. A dataset another Meta destination of the profile already holds is never written onto a second one (`409`, `destination_conflict`)." }, "lane": { "type": "string", "enum": [ "website", "whatsapp", "other" ], "description": "The lane of the destination that now carries the dataset: `website` = the pixel, every outcome without a click-to-WhatsApp click id; `whatsapp` = the WhatsApp dataset, only outcomes with one." }, "destination": { "type": "object", "properties": {} }, "privacy": { "$ref": "#/components/schemas/AdsPrivacyCheck" } }, "required": [ "action", "lane", "destination", "privacy" ] }, "AdsRuleSyncResult": { "type": "object", "properties": { "vertical": { "type": [ "string", "null" ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "action": { "type": "string", "enum": [ "created", "updated", "unchanged", "skipped" ], "description": "`unchanged` = the rule already held this body; nothing was written." }, "rule_id": { "type": [ "string", "null" ] }, "meta_enabled": { "type": "boolean" }, "meta_event_name": { "type": "string" }, "reason": { "type": "string", "enum": [ "definition_missing" ] } }, "required": [ "stage", "action", "rule_id", "meta_enabled", "meta_event_name" ] } } }, "required": [ "vertical", "rules" ] }, "AdsConversionSyncSetupResult": { "type": "object", "properties": { "destination": { "$ref": "#/components/schemas/AdsDestinationResult" }, "rules": { "$ref": "#/components/schemas/AdsRuleSyncResult" } }, "required": [ "destination", "rules" ] }, "AdsConversionSyncWiring": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "The conversion provider's per-rule × destination verdicts and remediation, verbatim: `{rule_id, destination_id, verdict, event_name, checks, remediation[], checked_at, stale}`, `verdict` ∈ `wired | sent_not_used | below_threshold | custom_conversion_broken | connection_broken | check_failed`. `checks` also carries Meta ids (`pixel.pixelId`, `optimizationGoal.usedByActiveAdSets[].adSetId` / `campaignId`), elided from the example." }, "checked_at": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "ttl_ms": { "type": "number" }, "privacy": { "$ref": "#/components/schemas/AdsPrivacyCheck" } }, "required": [ "results", "checked_at", "stale", "ttl_ms" ] }, "AdsSendStatus": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "not_started", "on", "partial", "off", "blocked", "measure_only" ], "description": "`blocked` = only Meta or the owner outside Vitrina can fix it (`blocked_reason`). `off` = set up once and every stage stopped. `measure_only` = the owner chose «Solo medir, no enviar a Meta» (reversible with `send_setup`)." }, "blocked_reason": { "type": [ "string", "null" ], "enum": [ "no_dataset", "datasets_unavailable" ] }, "wizard_done": { "type": "boolean", "description": "The activation wizard’s «Enviar a Meta» step is resolved: `state` is `on`, `partial`, `blocked` or `measure_only`." }, "meta_connection": { "type": "string", "enum": [ "connected", "not_connected", "reconnect_required", "unknown" ] }, "dataset": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string", "description": "Meta’s dataset (pixel) id." }, "id_tail": { "type": "string", "description": "Its last 4 digits («…4821»)." }, "name": { "type": [ "string", "null" ] }, "last_fired_at": { "type": [ "string", "null" ] }, "is_unavailable": { "type": [ "boolean", "null" ], "description": "`null` = Meta gave no verdict (unknown, not healthy)." } }, "required": [ "external_id", "id_tail", "name", "last_fired_at", "is_unavailable" ], "description": "The dataset Meta receives the events in today." }, "datasets": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Meta’s dataset (pixel) id." }, "id_tail": { "type": "string", "description": "Its last 4 digits («…4821»)." }, "name": { "type": [ "string", "null" ] }, "last_fired_at": { "type": [ "string", "null" ] }, "is_unavailable": { "type": [ "boolean", "null" ], "description": "`null` = Meta gave no verdict (unknown, not healthy)." }, "recommended": { "type": "boolean" }, "recommended_reason": { "type": [ "string", "null" ], "enum": [ "used_by_ad_sets", "most_recent", "only_one" ], "description": "`used_by_ad_sets` = active ad sets already optimise on it (keep it: Meta keeps learning where it learns)." }, "selected": { "type": "boolean" } }, "required": [ "external_id", "id_tail", "name", "last_fired_at", "is_unavailable", "recommended", "recommended_reason", "selected" ] }, "description": "The datasets of the connected ad account." }, "whatsapp_dataset": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "id_tail": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "external_id", "id_tail", "enabled" ], "description": "The WhatsApp lane’s own dataset when the profile has one beside `dataset`: outcomes that carry a click-to-WhatsApp click id reach Meta there (as `business_messaging`), everything else in `dataset`. `null` = one dataset carries everything. «Enviar a Meta» never moves either lane onto the other’s dataset." }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "label": { "type": "string", "description": "The stage in the workspace’s words." }, "meta_event": { "type": "string", "description": "What Meta receives." }, "meta_event_names": { "type": "array", "items": { "type": "string" }, "description": "Every event name Meta may receive for the stage, the headline first (`meta_event`), then the WhatsApp lane's name when it differs: a clinic's attended stage reads `['appointment_attended', 'QualifiedLead']` when a WhatsApp dataset is connected." }, "meta_event_messaging": { "type": [ "string", "null" ], "description": "The name the stage reaches Meta under on the WhatsApp dataset (one of the 14 names that dataset accepts, e.g. `QualifiedLead`). `null`: no WhatsApp dataset is connected, or the stage is skipped on that lane. The website pixel keeps `meta_event`." }, "meta_event_kind": { "type": "string", "enum": [ "standard", "custom" ] }, "meta_event_neutral": { "type": "boolean", "description": "A custom stage that reaches Meta under Vitrina’s opaque neutral name (`vitrina_step_3` attended, `vitrina_step_4` quote presented, `vitrina_step_5` accepted presupuesto, `vitrina_step_7` a returning customer’s first payment), which names no stage. `false` for a standard event, and for a custom stage that keeps its literal name (`appointment_attended`, …) because Meta already holds history under it." }, "value": { "type": "string", "enum": [ "accepted_total", "payment", "none" ], "description": "The value Meta receives with the event." }, "enabled": { "type": "boolean", "description": "It reaches Meta today." }, "switchable": { "type": "boolean" }, "lock": { "type": [ "string", "null" ], "enum": [ "installments" ], "description": "`installments`: a clinic’s later payments never reach Meta, so one sale is never counted twice. No switch." }, "awaiting_switch": { "type": "boolean", "description": "A clinic’s first payment before the switch: Meta does not receive it yet (its Purchase is still the accepted presupuesto). `send_stage:first_payment:on` makes the switch, with consent." }, "source": { "type": "string", "enum": [ "available", "no_payments_source", "definition_missing" ], "description": "`definition_missing` heals on its own (no user step); `no_payments_source` = no payments recorded to send yet." }, "ready": { "type": "boolean", "description": "If the stage happened now, it would reach Meta: switched on and its source has what it needs." }, "ready_reason": { "type": [ "string", "null" ], "enum": [ "installments", "awaiting_switch", "definition_missing", "no_payments_yet", "off" ], "description": "Why it would not reach Meta now; `null` when `ready`. Precedence: `installments` > `awaiting_switch` > `definition_missing` > `no_payments_yet` > `off`." }, "count_28d": { "type": "integer", "description": "Outcomes of the stage that happened in Vitrina over the page’s window — the last 30 days (`window_days`; the field name predates it), the same days the dataset preview counts — sent or not. `first_payment`: `first_payment_candidates.count_28d` (first payments of accepted plans, or — a clinic without plans — persons’ first payments), before the switch too." }, "weekly_28d": { "type": "number", "description": "«Por semana», one decimal: the mean of the last 4 COMPLETE weeks (Monday–Sunday, Santiago) in which the stage was being measured — a week before its first recorded outcome is left out, never counted as zero. With no complete measured week yet: the days measured so far × 7 (divisor floor of 7 days). The dataset preview’s `weekly` for the same stage is the same figure." }, "measured_weeks": { "type": "integer", "description": "Complete weeks `weekly_28d` averages, 0–4. 4 = «promedio de las últimas 4 semanas»; fewer = «promedio de N semanas»; 0 = estimated over `measured_days`." }, "measured_days": { "type": "integer", "description": "Days the stage has been measured, capped at the 30-day window; 0 = nothing recorded yet." }, "events_7d": { "type": "integer", "description": "Outcomes of the stage that happened in the last 7 days (Vitrina’s outbox)." }, "with_ad_click_7d": { "type": "integer", "description": "Of `events_7d`, those carrying the ad’s click id (`ctwa_clid`): the ones Meta can credit to a click-to-WhatsApp ad. The rest reach the dataset as a conversion without ad (a truthful non-messaging action_source)." }, "events_30d": { "type": "integer", "description": "Outcomes of the stage that happened in the last 30 days (`window_days`) in Vitrina’s outbox — what travelled (or waits) toward Meta. For a clinic’s `first_payment` this is NOT `count_28d` (the claims, which include first payments too old for Meta)." }, "with_ad_click_30d": { "type": "integer", "description": "Of `events_30d`, those carrying the ad’s click id (`ctwa_clid`): the WhatsApp dataset’s lane, the ones Meta credits to a click-to-WhatsApp ad." }, "without_ad_click_7d": { "type": "integer", "description": "`events_7d - with_ad_click_7d`: sent without the click, through the website pixel (or not sent without one)." }, "without_ad_click_30d": { "type": "integer", "description": "`events_30d - with_ad_click_30d`." }, "window_days": { "type": "number", "description": "The window `count_28d` covers: 30 days, the page’s «últimos 30 días»." }, "verdict": { "type": "string", "enum": [ "wired", "sent_not_used", "below_threshold", "custom_conversion_broken", "missing_custom_conversion", "connection_broken", "check_failed", "not_checked" ] }, "active_ad_sets": { "type": "integer" }, "last_sent_at": { "type": [ "string", "null" ] }, "sent_7d": { "type": "integer" }, "meta_volume_7d": { "type": [ "number", "null" ], "description": "What Meta counted for this event on the dataset over 7 days." }, "series_7d": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "America/Santiago day, `YYYY-MM-DD`." }, "count": { "type": "integer" } }, "required": [ "date", "count" ] } }, "weekly_learning_target": { "type": "integer" }, "changed_by": { "type": [ "string", "null" ], "description": "Who turned it off — a display name, only for a caller holding `memberships:read`." }, "changed_at": { "type": [ "string", "null" ] }, "value_capped_7d": { "type": "integer", "description": "Events of the last 7 days whose value Meta received capped at the workspace’s 95th percentile of accepted plans (≥ 20 plans). The full value stays in Vitrina’s reporting." }, "value_cap_clp": { "type": [ "number", "null" ], "description": "The cap applied, CLP." }, "too_old_28d": { "type": "integer", "description": "Of the outcomes that happened in the window (`window_days`), those handed over — or still waiting — more than 7 days after they happened: Meta refuses events older than 7 days, so these never reach it. Never retried. A history import of older outcomes is not counted." }, "purchases_reversed_28d": { "type": "integer", "description": "`first_payment` only: Purchases of the last 28 days whose payment was later reversed. Meta keeps them (it has no refund event)." }, "sample_arrival_ms": { "type": "integer", "description": "Sample mode only: when the scripted arrival plays." } }, "required": [ "stage", "label", "meta_event", "meta_event_names", "meta_event_messaging", "meta_event_kind", "meta_event_neutral", "value", "enabled", "switchable", "lock", "awaiting_switch", "source", "ready", "ready_reason", "count_28d", "weekly_28d", "measured_weeks", "measured_days", "events_7d", "with_ad_click_7d", "events_30d", "with_ad_click_30d", "without_ad_click_7d", "without_ad_click_30d", "window_days", "verdict", "active_ad_sets", "last_sent_at", "sent_7d", "meta_volume_7d", "series_7d", "weekly_learning_target", "changed_by", "changed_at", "value_capped_7d", "value_cap_clp", "too_old_28d", "purchases_reversed_28d" ] } }, "enabled_count": { "type": "integer", "description": "Counted stages that are `ready` — «{enabled_count} de {stage_count} etapas llegan a Meta». A switched-on stage whose source has no data yet is in `waiting_count` instead." }, "waiting_count": { "type": "integer", "description": "Counted stages switched on but not `ready` yet («1 espera pagos»). `enabled_count + waiting_count` = the switched-on counted stages." }, "stage_count": { "type": "integer", "description": "«{enabled_count} de {stage_count} etapas»; locked stages and the first payment before the switch excluded." }, "first_payment_candidates": { "type": [ "object", "null" ], "properties": { "basis": { "type": "string", "enum": [ "plan", "person" ], "description": "What the Purchase is the first payment OF. `plan`: the first payment of each accepted plan (a clinic that keeps presupuestos or a mirrored clinic system with plans). `person`: a clinic that keeps NO plans (no live presupuesto, no mirrored plan — read from its data, never a setting) — each person’s first payment > 0, once ever per person, valued at the amount paid (capped at the 95th percentile of the clinic’s payments of the last year once there are ≥ 20); later payments never reach Meta." }, "count_28d": { "type": "integer", "description": "First payments over the window (the last 30 days; the field name predates it), sent or not — what reaches Meta as Purchase once switched. `basis: plan`: first payments of accepted plans, in Vitrina’s payment ledger and in the clinic system’s mirror, one per sale. `basis: person`: persons whose first payment ever fell in the window." }, "weekly_28d": { "type": "number", "description": "«Por semana» of the new-patient first payments, one decimal — the mean of the last 4 complete measured weeks (see the stage’s `weekly_28d`), measured from the first claim." }, "measured_weeks": { "type": "integer", "description": "Complete weeks `weekly_28d` averages, 0–4." }, "measured_days": { "type": "integer", "description": "Days measured, capped at 30." }, "mirror_count_28d": { "type": [ "integer", "null" ], "description": "Of `count_28d`, the first payments claimed from the clinic system’s mirror (they reach Meta like the ledger’s). `null` without a mirror opt-in." }, "mirror_weekly_28d": { "type": [ "number", "null" ] } }, "required": [ "basis", "count_28d", "weekly_28d", "measured_weeks", "measured_days", "mirror_count_28d", "mirror_weekly_28d" ], "description": "Clinics: the Purchase volume of the first payment, counted before the switch too. `null` outside clinics or when it could not be read." }, "first_payment_click_match": { "type": [ "object", "null" ], "properties": { "stage": { "type": "string", "enum": [ "first_payment" ] }, "required_7d": { "type": "integer", "description": "Meta’s minimum: about 50 optimisation events per 7 days to leave the learning phase (Meta Business Help Center, «About the learning phase»)." }, "with_ad_click_7d": { "type": "integer", "description": "First payments of the last 7 days sent WITH the ad’s click id (`ctwa_clid`): the only ones the WhatsApp dataset can optimise on." }, "remaining_7d": { "type": "integer", "description": "`max(0, required_7d - with_ad_click_7d)`." }, "reached": { "type": "boolean" }, "without_ad_click_7d": { "type": "integer", "description": "First payments of the last 7 days sent without the click (website pixel lane): they never count toward `required_7d`." }, "with_ad_click_30d": { "type": "integer" }, "without_ad_click_30d": { "type": "integer" }, "held_back_30d": { "type": [ "object", "null" ], "properties": { "too_old": { "type": "integer", "description": "New patients’ first payments of the last 30 days already older than Meta’s 7-day event window when Vitrina claimed them (the clinic system’s history, a late entry): never sent." }, "no_contact": { "type": "integer", "description": "First payments with no patient contact to send them under (retried while fresh)." } }, "required": [ "too_old", "no_contact" ], "description": "Why first payments did not reach Meta at all. `null` for a clinic without plans or when it could not be read." } }, "required": [ "stage", "required_7d", "with_ad_click_7d", "remaining_7d", "reached", "without_ad_click_7d", "with_ad_click_30d", "without_ad_click_30d", "held_back_30d" ], "description": "Clinics: click-matched first payments toward Meta’s 50-per-week minimum («44 de 50»). `null` outside clinics." }, "restriction": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "none", "limited", "blocked", "unknown" ] }, "since": { "type": [ "string", "null" ] } }, "required": [ "kind", "since" ], "description": "Health-dataset restriction by Meta (clinics): `blocked` = Meta counted none of the Lead / Schedule / Purchase sent on ≥ 3 of the last 7 days. `unknown` when it could not be read; `none` outside clinics." }, "protected_dataset": { "type": [ "object", "null" ], "properties": { "state": { "type": "string", "enum": [ "provisioned", "missing", "preparing" ] }, "ad_sets_to_move": { "type": [ "integer", "null" ], "description": "Active ad sets still optimising on the restricted dataset (null = not read)." } }, "required": [ "state", "ad_sets_to_move" ], "description": "Clinics: the protected replacement dataset Vitrina prepares on its own when Meta restricts the dataset. Sending never waits for it; moving the ad sets is a separate, consented action. `null` outside clinics." }, "purchase_stage": { "type": [ "string", "null" ], "enum": [ "closed_won", "first_payment" ], "description": "Clinics: which stage carries the Meta Purchase today — the accepted presupuesto until the owner’s consented switch to the first payment. No rules sync ever moves it. `null` outside clinics." }, "purchase_switch_available": { "type": "boolean", "description": "The switch of the Purchase to the first payment can be made now." }, "recommended_optimization_stage": { "type": [ "object", "null" ], "properties": { "stage": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "reason": { "type": "string", "enum": [ "rate_band", "default" ] }, "rate": { "type": [ "number", "null" ] } }, "required": [ "stage", "reason", "rate" ], "description": "Advice only — Vitrina never changes an ad set’s goal: the earliest stage reached by 1–40 % of new contacts over 28 days, once there are ≥ 50 (what Meta learns best from with this volume); `default` = not enough data yet, the usual answer for the business type. Never a standard event on a health-restricted dataset." }, "grant": { "type": "string", "enum": [ "full", "read_only", "unknown" ], "description": "`read_only`: the Meta connection cannot manage ads — sending works, fixes that write in Meta do not." }, "protection_required": { "type": "boolean", "description": "Health data protection applies (clinics)." }, "protected": { "type": "boolean" }, "consent": { "type": [ "object", "null" ], "properties": { "version": { "type": "string" }, "current": { "type": "boolean" }, "accepted_at": { "type": "string" } }, "required": [ "version", "current", "accepted_at" ], "description": "The owner’s last acceptance of the send (the `send_setup` consent)." }, "meta_links": { "type": "object", "properties": { "create_dataset": { "type": [ "string", "null" ] }, "events_manager": { "type": [ "string", "null" ] }, "test_events": { "type": [ "string", "null" ] }, "ad_sets": { "type": [ "string", "null" ] } }, "required": [ "create_dataset", "events_manager", "test_events", "ad_sets" ], "description": "Meta links built on the server from Meta ids. Open in a new tab; they change nothing by themselves." }, "checked_at": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "sample": { "type": "boolean" }, "ad_set_goals": { "type": [ "object", "null" ], "properties": { "conversations": { "type": "integer", "description": "Active click-to-WhatsApp ad sets that optimise for CONVERSATIONS (the engine’s nightly Meta sync)." }, "on_sent_events": { "type": "integer", "description": "Distinct active ad sets that optimise on an event Vitrina sends (the wiring verdicts)." } }, "required": [ "conversations", "on_sent_events" ], "description": "What the ads optimise for today. `conversations > 0` with `on_sent_events = 0`: the events reach Meta but no ad set learns from them yet (a new ad set optimised for one of them is how to start). `null` = not read." } }, "required": [ "state", "blocked_reason", "wizard_done", "meta_connection", "dataset", "datasets", "stages", "enabled_count", "waiting_count", "stage_count", "first_payment_candidates", "first_payment_click_match", "restriction", "protected_dataset", "purchase_stage", "purchase_switch_available", "recommended_optimization_stage", "grant", "protection_required", "protected", "consent", "meta_links", "checked_at", "stale", "sample", "ad_set_goals" ] }, "AdsSendPreviewEvent": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "source": { "type": "string", "enum": [ "own", "example" ], "description": "`example` when the workspace has no event of this stage yet." }, "vitrina": { "type": "object", "properties": { "stage_label": { "type": "string" }, "occurred_at": { "type": "string" }, "value_clp": { "type": [ "number", "null" ], "description": "The workspace’s full value, CLP (before Meta’s cap)." }, "contact_tail": { "type": [ "string", "null" ], "description": "Last 4 characters of the contact’s opaque reference; never a name or a contact detail." } }, "required": [ "stage_label", "occurred_at", "value_clp", "contact_tail" ] }, "meta": { "type": "object", "properties": { "event": { "type": "string" }, "value_clp": { "type": [ "number", "null" ], "description": "The value Meta receives, CLP; `null` when Meta gets no value." }, "capped": { "type": "boolean", "description": "Meta receives the workspace’s 95th-percentile cap instead of the full value (`vitrina.value_clp`)." }, "value_cap_clp": { "type": [ "number", "null" ], "description": "The cap applied, CLP, when `capped`." }, "reaches_meta": { "type": "boolean" }, "not_sent_reason": { "type": [ "string", "null" ], "enum": [ "marketing_opt_out", "stage_off", "stage_locked" ] }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "event", "time", "value", "action_source", "email", "phone", "contact_ref", "national_id", "ad_click" ] }, "label": { "type": "string" }, "state": { "type": "string", "enum": [ "sent", "hashed", "withheld", "absent" ], "description": "`hashed`: it crosses only as a hash Meta can match, not read. Identifiers never carry a value." }, "display": { "type": "string", "description": "Non-identifying fields only (event, time, value, where it happened)." }, "display_channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "messenger" ], "description": "`action_source` only: the conversation’s channel when the event was born in a messaging thread; `null` when not, or unknown." } }, "required": [ "key", "label", "state" ] } } }, "required": [ "event", "value_clp", "capped", "value_cap_clp", "reaches_meta", "not_sent_reason", "fields" ] }, "never_sent": { "type": "array", "items": { "type": "string" }, "description": "What never leaves Vitrina, as keys (`national_id`, `clinical_data`, `notes`, …)." } }, "required": [ "stage", "source", "vitrina", "meta", "never_sent" ] }, "AdsSendTestResult": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "received", "rejected", "blocked" ], "description": "`rejected` = Meta refused it; `blocked` = Vitrina’s own privacy or legal gate held the payload back before Meta (an internal block, never Meta’s answer; `blocked_reason` says which)." }, "blocked_reason": { "type": [ "string", "null" ], "description": "`blocked` only: the internal gate’s reason code (e.g. `dpa_not_accepted`, `baa_not_approved`, `privacy_gate`). `null` otherwise." }, "test_event_code": { "type": "string" }, "event_id": { "type": [ "string", "null" ], "description": "Search for it in Events Manager → Test Events." }, "stage": { "type": [ "string", "null" ], "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "meta_event": { "type": [ "string", "null" ] }, "quality_warning": { "type": "boolean" }, "test_events_link": { "type": [ "string", "null" ] }, "simulated": { "type": "boolean" } }, "required": [ "result", "test_event_code", "event_id", "stage", "meta_event", "quality_warning", "test_events_link", "simulated" ] }, "AdsMessagingEventNames": { "type": "object", "properties": { "overrides": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "The stored choices, `{ stage: name | null }`." }, "accepted_events": { "type": "array", "items": { "type": "string" } }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "label": { "type": "string" }, "website_event": { "type": "string", "description": "The website pixel lane’s name (not configurable here)." }, "messaging_default": { "type": [ "string", "null" ], "description": "The matrix’s own WhatsApp-lane name; `null` = not sent there." }, "messaging_event": { "type": [ "string", "null" ], "description": "The WhatsApp-lane name in force: the workspace’s choice, else the default; `null` = not sent there." }, "overridden": { "type": "boolean" } }, "required": [ "stage", "label", "website_event", "messaging_default", "messaging_event", "overridden" ] } } }, "required": [ "overrides", "accepted_events", "stages" ] }, "AdsMessagingEventNamesPatchResult": { "allOf": [ { "$ref": "#/components/schemas/AdsMessagingEventNames" }, { "type": "object", "properties": { "sync": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "converged", "pending" ], "description": "`converged`: the engine’s live rules now hold the names in force. `pending`: stored, the engine write failed and the daily sweep retries it." }, "updated": { "type": "array", "items": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] } } }, "required": [ "state", "updated" ] } }, "required": [ "sync" ] } ] }, "AdsMessagingEventNamesPatch": { "type": "object", "properties": { "overrides": { "type": "object", "properties": { "lead_created": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "lead_qualified": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "appointment_booked": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "checkout_started": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "deposit_paid": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "appointment_attended": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "quote_presented": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "closed_won": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "first_payment": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "returning_first_payment": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "payment_received": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "seller_qualified": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "seller_visit_booked": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] }, "seller_deal_closed": { "type": [ "string", "null" ], "enum": [ "Purchase", "LeadSubmitted", "InitiateCheckout", "AddToCart", "ViewContent", "OrderCreated", "OrderShipped", "OrderDelivered", "OrderCanceled", "OrderReturned", "CartAbandoned", "QualifiedLead", "RatingProvided", "ReviewProvided" ] } }, "description": "Per stage, the name the WhatsApp dataset receives: one of `accepted_events`, or `null` = the stage is not sent on the WhatsApp lane. Stages left out keep what they have." }, "reset": { "type": "array", "items": { "type": "string", "enum": [ "lead_created", "lead_qualified", "appointment_booked", "checkout_started", "deposit_paid", "appointment_attended", "quote_presented", "closed_won", "first_payment", "returning_first_payment", "payment_received", "seller_qualified", "seller_visit_booked", "seller_deal_closed" ] }, "maxItems": 14, "description": "Stages whose choice is dropped: they go back to the matrix's name (`messaging_default`). Applied before `overrides`." } }, "additionalProperties": false }, "AdsMetaDatasetStatus": { "type": "object", "properties": { "prerequisites": { "type": "object", "properties": { "meta_ads_connected": { "type": [ "boolean", "null" ] }, "whatsapp_connected": { "type": [ "boolean", "null" ] }, "instagram_connected": { "type": [ "boolean", "null" ], "description": "`null` while the measurement engine does not report it." } }, "required": [ "meta_ads_connected", "whatsapp_connected", "instagram_connected" ] }, "whatsapp": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "whatsapp", "website", "instagram" ] }, "state": { "type": "string", "enum": [ "coming_soon", "unknown", "prerequisites_missing", "ready", "created", "sending", "off", "error" ], "description": "`coming_soon` = the measurement engine cannot do this step yet («Pronto»); `unknown` = the engine could not be read now; `prerequisites_missing` = connect Meta Ads (and WhatsApp for the WhatsApp step, Instagram for the Instagram step) first; `ready` = the press would act; `created` = wired but no enabled Meta rule yet, so nothing flows; `sending` = the engine confirms an enabled destination AND an enabled Meta rule; `off` = turned off, receives nothing; `error` = see `reason_code` / `message`." }, "reason_code": { "type": [ "string", "null" ], "enum": [ "entitlement_required", "duplicate_kind", "access_missing", "dataset_unreadable", "already_exists", "no_pixel", "pixels_unavailable", "pixel_already_attached", "instagram_facebook_login_required", "meta_refused", "meta_unavailable", "engine_error" ] }, "message": { "type": [ "string", "null" ], "description": "What to do, in Spanish, when `reason_code` is set." }, "dataset": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string", "description": "Meta’s dataset / pixel id." }, "id_tail": { "type": "string" }, "export_from": { "type": [ "string", "null" ], "description": "Only what happens from this instant on is sent; never history." }, "destination_enabled": { "type": [ "boolean", "null" ] }, "access_granted": { "type": [ "boolean", "null" ] }, "shared": { "type": "boolean", "description": "Another workspace already sends to this ad account or dataset." } }, "required": [ "external_id", "id_tail", "export_from", "destination_enabled", "access_granted", "shared" ] }, "can_create": { "type": "boolean" }, "can_turn_off": { "type": "boolean" }, "notice": { "type": "object", "properties": { "version": { "type": "string" }, "points": { "type": "array", "items": { "type": "string" }, "description": "Read before this step’s confirmation, verbatim (Spanish)." }, "hash": { "type": "string", "description": "SHA-256 of the points; sent back with the press." } }, "required": [ "version", "points", "hash" ] } }, "required": [ "kind", "state", "reason_code", "message", "dataset", "can_create", "can_turn_off", "notice" ], "description": "Step 1 — the dataset linked to the WhatsApp Business Account: receives the outcomes carrying the click-to-WhatsApp ad click, as `business_messaging`." }, "website": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "whatsapp", "website", "instagram" ] }, "state": { "type": "string", "enum": [ "coming_soon", "unknown", "prerequisites_missing", "ready", "created", "sending", "off", "error" ], "description": "`coming_soon` = the measurement engine cannot do this step yet («Pronto»); `unknown` = the engine could not be read now; `prerequisites_missing` = connect Meta Ads (and WhatsApp for the WhatsApp step, Instagram for the Instagram step) first; `ready` = the press would act; `created` = wired but no enabled Meta rule yet, so nothing flows; `sending` = the engine confirms an enabled destination AND an enabled Meta rule; `off` = turned off, receives nothing; `error` = see `reason_code` / `message`." }, "reason_code": { "type": [ "string", "null" ], "enum": [ "entitlement_required", "duplicate_kind", "access_missing", "dataset_unreadable", "already_exists", "no_pixel", "pixels_unavailable", "pixel_already_attached", "instagram_facebook_login_required", "meta_refused", "meta_unavailable", "engine_error" ] }, "message": { "type": [ "string", "null" ], "description": "What to do, in Spanish, when `reason_code` is set." }, "dataset": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string", "description": "Meta’s dataset / pixel id." }, "id_tail": { "type": "string" }, "export_from": { "type": [ "string", "null" ], "description": "Only what happens from this instant on is sent; never history." }, "destination_enabled": { "type": [ "boolean", "null" ] }, "access_granted": { "type": [ "boolean", "null" ] }, "shared": { "type": "boolean", "description": "Another workspace already sends to this ad account or dataset." } }, "required": [ "external_id", "id_tail", "export_from", "destination_enabled", "access_granted", "shared" ] }, "can_create": { "type": "boolean" }, "can_turn_off": { "type": "boolean" }, "notice": { "type": "object", "properties": { "version": { "type": "string" }, "points": { "type": "array", "items": { "type": "string" }, "description": "Read before this step’s confirmation, verbatim (Spanish)." }, "hash": { "type": "string", "description": "SHA-256 of the points; sent back with the press." } }, "required": [ "version", "points", "hash" ] }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Meta’s pixel id." }, "id_tail": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "last_fired_at": { "type": [ "string", "null" ] }, "recommended": { "type": "boolean" } }, "required": [ "external_id", "id_tail", "name", "last_fired_at", "recommended" ] }, "description": "The ad account’s pixels to choose from (only while the step is `ready` / `off`)." }, "can_create_pixel": { "type": "boolean", "description": "The ad account has no pixel (`reason_code: no_pixel`): `POST /ads/conversion-sync/data-sources/website/create-pixel` would create one and connect it." } }, "required": [ "kind", "state", "reason_code", "message", "dataset", "can_create", "can_turn_off", "notice", "candidates", "can_create_pixel" ], "description": "Step 2 — the website pixel: receives every outcome without the ad click, matched by the hashed phone and e-mail." }, "instagram": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "whatsapp", "website", "instagram" ] }, "state": { "type": "string", "enum": [ "coming_soon", "unknown", "prerequisites_missing", "ready", "created", "sending", "off", "error" ], "description": "`coming_soon` = the measurement engine cannot do this step yet («Pronto»); `unknown` = the engine could not be read now; `prerequisites_missing` = connect Meta Ads (and WhatsApp for the WhatsApp step, Instagram for the Instagram step) first; `ready` = the press would act; `created` = wired but no enabled Meta rule yet, so nothing flows; `sending` = the engine confirms an enabled destination AND an enabled Meta rule; `off` = turned off, receives nothing; `error` = see `reason_code` / `message`." }, "reason_code": { "type": [ "string", "null" ], "enum": [ "entitlement_required", "duplicate_kind", "access_missing", "dataset_unreadable", "already_exists", "no_pixel", "pixels_unavailable", "pixel_already_attached", "instagram_facebook_login_required", "meta_refused", "meta_unavailable", "engine_error" ] }, "message": { "type": [ "string", "null" ], "description": "What to do, in Spanish, when `reason_code` is set." }, "dataset": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string", "description": "Meta’s dataset / pixel id." }, "id_tail": { "type": "string" }, "export_from": { "type": [ "string", "null" ], "description": "Only what happens from this instant on is sent; never history." }, "destination_enabled": { "type": [ "boolean", "null" ] }, "access_granted": { "type": [ "boolean", "null" ] }, "shared": { "type": "boolean", "description": "Another workspace already sends to this ad account or dataset." } }, "required": [ "external_id", "id_tail", "export_from", "destination_enabled", "access_granted", "shared" ] }, "can_create": { "type": "boolean" }, "can_turn_off": { "type": "boolean" }, "notice": { "type": "object", "properties": { "version": { "type": "string" }, "points": { "type": "array", "items": { "type": "string" }, "description": "Read before this step’s confirmation, verbatim (Spanish)." }, "hash": { "type": "string", "description": "SHA-256 of the points; sent back with the press." } }, "required": [ "version", "points", "hash" ] } }, "required": [ "kind", "state", "reason_code", "message", "dataset", "can_create", "can_turn_off", "notice" ], "description": "Step 3 — the dataset linked to the Instagram account: receives the outcomes of conversations an Instagram ad opened, as `business_messaging` with the customer’s Instagram-scoped id and the business account id (never message content). Measurement only: Meta offers no Purchase optimisation on Instagram. Until it is created those outcomes reach the website pixel as before." }, "click_less_not_sent": { "type": "boolean", "description": "Step 1 is wired and no pixel is: the outcomes without the ad click (most payments) are not sent to Meta at all." }, "preview": { "type": [ "object", "null" ], "properties": { "window_days": { "type": "integer" }, "total": { "type": "integer" }, "with_ad_click": { "type": "integer" }, "without_ad_click": { "type": "integer" }, "click_less_to": { "type": "string", "enum": [ "website_pixel", "not_sent" ], "description": "Where click-less events go: the website pixel (with a non-messaging action_source) or, without one, nowhere." }, "enabled_meta_rules": { "type": [ "integer", "null" ] }, "source": { "type": "string", "enum": [ "engine", "vitrina" ] }, "truncated": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string" }, "label": { "type": "string", "description": "The stage in the workspace’s own words." }, "on": { "type": "boolean", "description": "Switched on in «Envío a Meta» (it ships when its rule does)." }, "total": { "type": "integer" }, "with_ad_click": { "type": "integer", "description": "Of `total`, those carrying the click-to-WhatsApp ad click (`ctwa_clid`): the ones the WhatsApp dataset can credit to an ad." }, "weekly": { "type": "number" }, "weekly_with_ad_click": { "type": "number" }, "measured_weeks": { "type": "integer" }, "measured_days": { "type": "integer" } }, "required": [ "stage", "label", "on", "total", "with_ad_click", "weekly", "weekly_with_ad_click", "measured_weeks", "measured_days" ] } } }, "required": [ "window_days", "total", "with_ad_click", "without_ad_click", "click_less_to", "enabled_meta_rules", "source", "truncated", "stages" ], "description": "What would have flowed over the last 30 days. Nothing is sent by reading it." } }, "required": [ "prerequisites", "whatsapp", "website", "instagram", "click_less_not_sent", "preview" ] }, "PaymentInstrumentRequirement": { "type": "object", "properties": { "instrument": { "type": "string", "enum": [ "efectivo", "transferencia", "cheque", "vale_vista", "tarjeta", "tarjeta_debito", "tarjeta_credito", "bono", "otro", "mercadopago", "webpay", "fintoc", "flow", "khipu", "bancame" ] }, "required_fields": { "type": "array", "items": { "type": "string", "enum": [ "bank", "account_number", "document_number", "note" ] }, "description": "Fields that must be non-blank for this instrument. Empty = only paid_on and amount_clp." } }, "required": [ "instrument", "required_fields" ] }, "AdOrigin": { "type": [ "object", "null" ], "properties": { "platform": { "type": "string", "enum": [ "whatsapp", "instagram", "messenger" ], "description": "Where the thread lives — the conversation channel." }, "kind": { "type": "string", "enum": [ "ad", "post" ], "description": "`post` when the person tapped a boosted post, else `ad`." }, "ad_external_id": { "type": [ "string", "null" ], "description": "Meta's ad id; `null` for a post or when Meta sent none." }, "ad_name": { "type": [ "string", "null" ], "description": "The ad name in the ad account; `null` when unknown." }, "campaign_name": { "type": [ "string", "null" ], "description": "The ad's campaign name; `null` when unknown." }, "title": { "type": [ "string", "null" ], "description": "The ad's headline — the ADVERTISER'S copy, never the customer's words." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "Still image of the creative: our durable copy when `media_archived`, else Meta’s own link." }, "media_archived": { "type": "boolean", "description": "`true` when `thumbnail_url` is Vitrina’s durable copy; `false` when it is a Meta CDN link that expires (render with a fallback) or absent." }, "video_url": { "type": [ "string", "null" ], "description": "The creative’s video when a video ad (a Meta CDN link — it expires)." }, "source_url": { "type": [ "string", "null" ], "description": "Permalink to the ad or the post it promotes, when known." }, "captured_at": { "type": [ "string", "null" ], "description": "When the thread opened from the ad (the conversation creation time)." } }, "required": [ "platform", "kind", "ad_external_id", "ad_name", "campaign_name", "title", "thumbnail_url", "media_archived", "video_url", "source_url", "captured_at" ] }, "ConversationCampaignOrigin": { "type": [ "object", "null" ], "properties": { "campaign_id": { "type": "string", "format": "uuid" }, "campaign_name": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "started_by_campaign": { "type": "boolean", "description": "The send CREATED this thread (born closed, `source = campaign`)." }, "awaiting_reply": { "type": "boolean", "description": "The newest message in the thread is that send — «Enviada · sin respuesta»." } }, "required": [ "campaign_id", "campaign_name", "sent_at", "started_by_campaign", "awaiting_reply" ], "description": "List rows only: the newest campaign send stored in the thread (`null` when none)." }, "ConversationReplyVia": { "type": [ "object", "null" ], "properties": { "channel": { "type": "string", "enum": [ "whatsapp" ] }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The contact's most recent open WhatsApp conversation in this workspace — answer there. `null`: none yet; open one with `POST /conversations/whatsapp` and send a template through `POST /conversations/{id}/templates`." }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "contact_phone": { "type": [ "string", "null" ] } }, "required": [ "channel", "conversation_id", "contact_id", "contact_phone" ], "description": "Non-null ONLY when this conversation cannot carry a reply (a website form, `website`, or a Yapo lead, `yapo`): every send on it answers 409 `CHANNEL_READ_ONLY`, and this names the WhatsApp thread to use instead. Absent on every channel that can reply." }, "MessageAttachment": { "type": "object", "properties": { "index": { "type": "integer", "description": "Position in `media_urls`." }, "url": { "type": "string", "description": "`media_urls[index]`, verbatim." }, "mime": { "type": [ "string", "null" ], "description": "MIME of the original when the row records it (`metadata.mime` on a one-file row); null otherwise." }, "playback_url": { "type": [ "string", "null" ], "description": "A URL iOS can play for this audio attachment, or null (not audio, or the AAC rendition is not ready yet — ask `GET /messages/{id}/audio-playback?attachment={index}`)." }, "playback_mime": { "type": [ "string", "null" ], "enum": [ "audio/mp4", "audio/mpeg", "audio/aac" ], "description": "`audio/mp4` for an AAC rendition (or an mp4/m4a original), `audio/mpeg` / `audio/aac` for an mp3 / aac original served as is; null exactly when `playback_url` is." } }, "required": [ "index", "url", "mime", "playback_url", "playback_mime" ] }, "MessageForm": { "type": "object", "properties": { "title": { "type": "string" }, "highlight": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ], "description": "The headline figure, e.g. «Cotización» · «hasta $500.000»." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "value": { "type": "string" } }, "required": [ "label", "value" ] } } }, "required": [ "fields" ] }, "Message": { "type": "object", "properties": { "id": { "type": "string" }, "conversation_id": { "type": "string" }, "sender_type": { "type": "string", "enum": [ "contact", "ai_agent", "human_user", "system", "api_key" ] }, "sender_id": { "type": [ "string", "null" ], "description": "contact id / ai_agent id / member user id / api_key id; null for system." }, "sender_name": { "type": [ "string", "null" ], "description": "Display name of the sender (a member's profile name, the AI agent's, the API key's name when it sent). Prefer `author`." }, "sender_avatar": { "type": [ "string", "null" ] }, "author": { "$ref": "#/components/schemas/Author" }, "content": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "media_urls": { "type": [ "array", "null" ], "items": { "type": "string" } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" }, "description": "One entry per `media_urls` entry, same order — see MessageAttachment." }, "metadata": { "type": [ "object", "null" ], "properties": { "form": { "$ref": "#/components/schemas/MessageForm" } }, "description": "Channel-specific extras. `form` is set on the first message of a website-form conversation (see MessageForm)." }, "created_at": { "type": "string" } }, "required": [ "id", "conversation_id", "sender_type", "sender_id", "author", "content", "type", "created_at" ] }, "PendingApproval": { "type": "object", "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending_approval" ] }, "action_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" } }, "required": [ "status", "action_id", "message" ] } }, "required": [ "data" ] }, "OutboundVerdictError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "OUTBOUND_BLOCKED", "OUTBOUND_WARNING" ] }, "message": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "contact_blocked", "contact_spam", "channel_suppressed", "scope_blocked", "marketing_consent_missing", "email_not_subscribed", "outbound_hold_active", "window_closed", "template_missing", "template_not_approved", "template_unsupported", "template_params_incomplete", "template_category_unknown", "template_category_mismatch", "legal_basis_mismatch", "no_channel_identity", "account_disconnected", "account_quality_red", "past_max_lateness", "quiet_hours", "conversation_human_owned", "account_quality_degraded", "conversation_closed", "contact_archived", "contact_merged", "stale_context", "input_unresolved", "loop_same_content", "loop_burst", "copy_address_blocked" ] } }, "hint": { "type": "string" }, "details": { "type": "object", "properties": { "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "contact_blocked", "contact_spam", "channel_suppressed", "scope_blocked", "marketing_consent_missing", "email_not_subscribed", "outbound_hold_active", "window_closed", "template_missing", "template_not_approved", "template_unsupported", "template_params_incomplete", "template_category_unknown", "template_category_mismatch", "legal_basis_mismatch", "no_channel_identity", "account_disconnected", "account_quality_red", "past_max_lateness", "quiet_hours", "conversation_human_owned", "account_quality_degraded", "conversation_closed", "contact_archived", "contact_merged", "stale_context", "input_unresolved", "loop_same_content", "loop_burst", "copy_address_blocked" ] }, "kind": { "type": "string", "enum": [ "bloqueo", "advertencia" ] }, "hint": { "type": "string" }, "detail": { "type": "object", "additionalProperties": {} } }, "required": [ "code", "kind", "hint", "detail" ] } } }, "required": [ "reasons" ] }, "requestId": { "type": "string" } }, "required": [ "code", "message", "reasons", "hint", "details" ] } }, "required": [ "error" ] }, "SequenceMessageStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "situation": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "message" ] }, "position": { "type": "integer" }, "channel": { "type": "string", "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "fallback_channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "wait": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "duration" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "from": { "type": "string", "enum": [ "previous_step", "start" ] }, "from_step": { "type": [ "string", "null" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "from", "from_step", "hours" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string" } }, "required": [ "type", "event" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agreed_time" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "before_appointment" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "hours" ], "description": "Custom sequences: this long before the booked appointment (a reminder). Only with entry `appointment_booked`." } ] }, "wait_after_previous": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "at_hours": { "type": [ "number", "null" ] }, "mode": { "type": "string", "enum": [ "auto", "auto_unless_assigned", "approval", "skip" ] }, "mode_effective": { "type": "string", "enum": [ "auto", "auto_unless_assigned", "approval", "skip" ] }, "sends": { "type": "boolean" }, "not_sent_reason": { "type": [ "string", "null" ] }, "needs_template": { "type": "boolean" }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ai_message" ] }, "template_after_window": { "type": "boolean" } }, "required": [ "type", "template_after_window" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "template_ladder" ] }, "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" } }, "required": [ "name", "language" ] } } }, "required": [ "type", "templates" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "subject": { "type": [ "string", "null" ] }, "custom_body": { "type": "boolean" } }, "required": [ "type", "subject", "custom_body" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "promise" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] } ] }, "config_ref": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "rail": { "type": "string", "enum": [ "unanswered_message", "stalled", "never_replied", "lost" ] }, "step": { "type": "integer" }, "after_hours": { "type": "number" }, "unit": { "type": [ "string", "null" ], "enum": [ "d", "h" ] }, "autonomy": { "type": "string", "enum": [ "auto", "assignee", "approval" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "email", "voice" ] }, "min_score": { "type": [ "number", "null" ] } }, "required": [ "type", "rail", "step", "after_hours", "unit", "autonomy", "channel", "min_score" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "source": { "type": "string" }, "config_origin": { "type": "string", "enum": [ "configured", "inherited", "platform_default" ] } }, "required": [ "type", "source", "config_origin" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "sequence_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "sequence_id" ] } ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object", "properties": { "waiting_now": { "type": [ "integer", "null" ] }, "sent_30d": { "type": "integer" }, "reply_rate_30d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "daily_14d": { "type": "array", "items": { "type": "integer" } } }, "required": [ "waiting_now", "sent_30d", "reply_rate_30d", "daily_14d" ] } }, "required": [ "id", "key", "situation", "kind", "position", "channel", "fallback_channel", "wait", "wait_after_previous", "at_hours", "mode", "mode_effective", "sends", "not_sent_reason", "needs_template", "content", "config_ref", "warnings", "stats" ] }, "SequenceBranch": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 60 }, "label": { "type": "string", "maxLength": 120 }, "to": { "type": [ "string", "null" ], "maxLength": 120, "description": "A step key, `end` (the sequence ends), or null = the next step by position." } }, "required": [ "key", "label", "to" ] }, "SequenceConditionStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "situation": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "condition" ] }, "position": { "type": "integer" }, "label": { "type": "string" }, "wait": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "duration" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "from": { "type": "string", "enum": [ "previous_step", "start" ] }, "from_step": { "type": [ "string", "null" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "from", "from_step", "hours" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string" } }, "required": [ "type", "event" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agreed_time" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "before_appointment" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "hours" ], "description": "Custom sequences: this long before the booked appointment (a reminder). Only with entry `appointment_booked`." } ] }, "wait_after_previous": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "at_hours": { "type": [ "number", "null" ] }, "test": { "type": "string", "enum": [ "replied", "paid", "booked", "ai_decides", "call_outcome" ], "description": "`replied` (the customer wrote since our last message), `paid` (unavailable until app#6456), `booked` (an appointment since entering), `ai_decides` (the sequence agent picks a branch; `default_branch` on failure). `call_outcome` (how the latest AI call step ended: one branch per outcome answered | promised_pay | promised_visit | call_later | no_answer | do_not_contact, 2 to 6, the branch key is the outcome; `default_branch` for an outcome with no branch). The fixed tests (replied, paid, booked) have exactly the branches `yes` and `no`." }, "ai_prompt": { "type": [ "string", "null" ] }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceBranch" } }, "default_branch": { "type": [ "string", "null" ] }, "config_ref": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "rail": { "type": "string", "enum": [ "unanswered_message", "stalled", "never_replied", "lost" ] }, "step": { "type": "integer" }, "after_hours": { "type": "number" }, "unit": { "type": [ "string", "null" ], "enum": [ "d", "h" ] }, "autonomy": { "type": "string", "enum": [ "auto", "assignee", "approval" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "email", "voice" ] }, "min_score": { "type": [ "number", "null" ] } }, "required": [ "type", "rail", "step", "after_hours", "unit", "autonomy", "channel", "min_score" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "source": { "type": "string" }, "config_origin": { "type": "string", "enum": [ "configured", "inherited", "platform_default" ] } }, "required": [ "type", "source", "config_origin" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "sequence_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "sequence_id" ] } ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object", "properties": { "waiting_now": { "type": [ "integer", "null" ] }, "sent_30d": { "type": "integer" }, "reply_rate_30d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "daily_14d": { "type": "array", "items": { "type": "integer" } } }, "required": [ "waiting_now", "sent_30d", "reply_rate_30d", "daily_14d" ] } }, "required": [ "id", "key", "situation", "kind", "position", "label", "wait", "wait_after_previous", "at_hours", "test", "ai_prompt", "branches", "default_branch", "config_ref", "warnings", "stats" ] }, "SequenceWaitUntil": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "date_field" ] }, "field": { "type": "string", "enum": [ "promised_date" ] } }, "required": [ "kind", "field" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string", "enum": [ "paid" ] } }, "required": [ "kind", "event" ] } ], "description": "`date_field promised_date`: the day set with POST /sequences/{id}/enrollments/{enrollment_id}/promised-date. `event paid`: unavailable until app#6456." }, "SequenceWaitUntilStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "situation": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "wait_until" ] }, "position": { "type": "integer" }, "label": { "type": "string" }, "until": { "$ref": "#/components/schemas/SequenceWaitUntil" }, "timeout": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "at_hours": { "type": [ "number", "null" ] }, "config_ref": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "rail": { "type": "string", "enum": [ "unanswered_message", "stalled", "never_replied", "lost" ] }, "step": { "type": "integer" }, "after_hours": { "type": "number" }, "unit": { "type": [ "string", "null" ], "enum": [ "d", "h" ] }, "autonomy": { "type": "string", "enum": [ "auto", "assignee", "approval" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "email", "voice" ] }, "min_score": { "type": [ "number", "null" ] } }, "required": [ "type", "rail", "step", "after_hours", "unit", "autonomy", "channel", "min_score" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "source": { "type": "string" }, "config_origin": { "type": "string", "enum": [ "configured", "inherited", "platform_default" ] } }, "required": [ "type", "source", "config_origin" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "sequence_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "sequence_id" ] } ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object", "properties": { "waiting_now": { "type": [ "integer", "null" ] }, "sent_30d": { "type": "integer" }, "reply_rate_30d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "daily_14d": { "type": "array", "items": { "type": "integer" } } }, "required": [ "waiting_now", "sent_30d", "reply_rate_30d", "daily_14d" ] } }, "required": [ "id", "key", "situation", "kind", "position", "label", "until", "timeout", "at_hours", "config_ref", "warnings", "stats" ] }, "SequenceGotoStep": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "situation": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "goto" ] }, "position": { "type": "integer" }, "label": { "type": "string" }, "target_step": { "type": "string" }, "max_times": { "type": "integer", "minimum": 1, "maximum": 5 }, "at_hours": { "type": [ "number", "null" ] }, "config_ref": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "rail": { "type": "string", "enum": [ "unanswered_message", "stalled", "never_replied", "lost" ] }, "step": { "type": "integer" }, "after_hours": { "type": "number" }, "unit": { "type": [ "string", "null" ], "enum": [ "d", "h" ] }, "autonomy": { "type": "string", "enum": [ "auto", "assignee", "approval" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "email", "voice" ] }, "min_score": { "type": [ "number", "null" ] } }, "required": [ "type", "rail", "step", "after_hours", "unit", "autonomy", "channel", "min_score" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "source": { "type": "string" }, "config_origin": { "type": "string", "enum": [ "configured", "inherited", "platform_default" ] } }, "required": [ "type", "source", "config_origin" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "sequence_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "sequence_id" ] } ] }, "warnings": { "type": "array", "items": { "type": "string" } }, "stats": { "type": "object", "properties": { "waiting_now": { "type": [ "integer", "null" ] }, "sent_30d": { "type": "integer" }, "reply_rate_30d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "daily_14d": { "type": "array", "items": { "type": "integer" } } }, "required": [ "waiting_now", "sent_30d", "reply_rate_30d", "daily_14d" ] } }, "required": [ "id", "key", "situation", "kind", "position", "label", "target_step", "max_times", "at_hours", "config_ref", "warnings", "stats" ] }, "SequenceStep": { "oneOf": [ { "$ref": "#/components/schemas/SequenceMessageStep" }, { "$ref": "#/components/schemas/SequenceConditionStep" }, { "$ref": "#/components/schemas/SequenceWaitUntilStep" }, { "$ref": "#/components/schemas/SequenceGotoStep" } ], "discriminator": { "propertyName": "kind", "mapping": { "message": "#/components/schemas/SequenceMessageStep", "condition": "#/components/schemas/SequenceConditionStep", "wait_until": "#/components/schemas/SequenceWaitUntilStep", "goto": "#/components/schemas/SequenceGotoStep" } } }, "Sequence": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "kind": { "type": "string", "enum": [ "builtin", "custom" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "draft" ] }, "entry": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string", "enum": [ "lead_arrived", "customer_went_quiet", "customer_asked_reminder", "stage_changed", "quoted_not_booked", "appointment_booked", "signed_up_not_bought", "installment_overdue" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "maxLength": 40, "description": "Custom sequences filter on `interest`, `source`, `stage` (stage id) or `tag` (tag name)." }, "op": { "type": "string", "enum": [ "in" ] }, "values": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 } }, "required": [ "field", "op", "values" ] }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "days_overdue", "amount" ], "description": "Only for the `installment_overdue` entry: `days_overdue` (days past the due day) or `amount` (pesos still owed), at least `value`." }, "op": { "type": "string", "enum": [ "gte" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "field", "op", "value" ] } ] } } }, "required": [ "type", "event", "filters" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type", "list_id" ] } ] }, "goal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply", "promise_kept", "books_visit", "books_demo", "pays" ] }, "label": { "type": "string" } }, "required": [ "type", "label" ] }, "agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "collection": { "type": "boolean", "description": "A collection sequence (Cobranza): it obeys the workspace’s collection rules (`GET /sequences/collection-rules`) and needs a recorded legal review to publish (`POST /sequences/{id}/legal-review`). True for the «Cobranza de cuotas» template, an entry of `installment_overdue` or a goal of `pays`." }, "priority": { "type": "integer" }, "situations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "first_step": { "type": [ "string", "null" ] }, "waiting_now": { "type": [ "integer", "null" ] }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "name", "enabled", "first_step", "waiting_now", "notes" ] } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceStep" } }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "kind": { "type": "string", "enum": [ "next", "reply_exit", "end", "branch", "loop" ] }, "situation": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ], "description": "Drawn on the arrow (vitrina-app#6454): the branch label, the loop bound, «Después de 2 vueltas»." }, "branch": { "type": [ "string", "null" ], "description": "`branch` connections: the condition branch key." }, "max_times": { "type": [ "integer", "null" ], "description": "`loop` connections: the goto bound." } }, "required": [ "from", "to", "kind", "situation" ] } }, "window_markers": { "type": "array", "items": { "type": "object", "properties": { "situation": { "type": [ "string", "null" ] }, "after_step": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "situation", "after_step", "label" ] } }, "ends": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "situation": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "mark_lost", "finish", "continue", "handoff" ] }, "after": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "at_hours": { "type": [ "number", "null" ] }, "label": { "type": "string" }, "detail": { "type": [ "string", "null" ] }, "continues_in": { "type": [ "object", "null" ], "properties": { "sequence_key": { "type": "string" }, "situation": { "type": [ "string", "null" ] } }, "required": [ "sequence_key", "situation" ] } }, "required": [ "key", "situation", "type", "after", "at_hours", "label", "detail", "continues_in" ] } }, "stats": { "type": "object", "properties": { "waiting_now": { "type": [ "integer", "null" ] }, "sent_30d": { "type": "integer" }, "reply_rate_30d": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "daily_14d": { "type": "array", "items": { "type": "integer" } } }, "required": [ "waiting_now", "sent_30d", "reply_rate_30d", "daily_14d" ] }, "published_version": { "type": [ "integer", "null" ], "description": "The newest published version number; null until the first draft (app#6448)." }, "draft": { "type": [ "object", "null" ], "properties": { "version_id": { "type": "string", "format": "uuid" }, "change_count": { "type": "integer" }, "updated_at": { "type": "string" } }, "required": [ "version_id", "change_count", "updated_at" ], "description": "The open draft, if any («Borrador · N cambios»)." } }, "required": [ "id", "key", "kind", "name", "description", "status", "entry", "goal", "agent_id", "collection", "priority", "situations", "steps", "connections", "window_markers", "ends", "stats" ] }, "SequenceCallOutcome": { "type": "string", "enum": [ "answered", "promised_pay", "promised_visit", "call_later", "no_answer", "do_not_contact" ], "description": "AI call steps only: the outcome the scenario supplied (default no_answer)." }, "SequenceSimulation": { "type": "object", "properties": { "timeline": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "channel": { "type": "string", "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "planned_at": { "type": "string", "format": "date-time" }, "shifted_at": { "type": "string", "format": "date-time" }, "shift_reason": { "type": "string", "enum": [ "outside_contact_hours", "previous_late", "unanswered_hold", "agreed_reminder", "min_gap", "max_per_day", "automated_gap", "person_ceiling", "appointment_soon", "daily_cap", "non_collection_day", "holiday", "outside_collection_hours", "min_spacing", "calls_per_day", "calls_per_week", "messages_per_week" ] }, "skip_reason": { "type": "string", "enum": [ "non_collection_day", "holiday", "outside_collection_hours", "min_spacing", "calls_per_day", "calls_per_week", "messages_per_week" ], "description": "Why the collection rules skipped the step (status `skipped_by_collection_rules`)." }, "preview": { "type": "string" }, "call_outcome": { "$ref": "#/components/schemas/SequenceCallOutcome" }, "status": { "type": "string", "enum": [ "sends", "awaits_approval", "skipped_no_channel", "skipped_no_template", "skipped_by_collection_rules" ] }, "iteration": { "type": "integer", "minimum": 2, "description": "Custom sequences: 2 on the first lap back through a loop, 3 on the next (absent = first pass)." } }, "required": [ "step_id", "step_key", "channel", "planned_at", "shifted_at", "status" ] } }, "end": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "replied", "paid", "end_of_sequence", "marked_lost", "no_fitting_approved_message", "no_channel_left", "blocked_by_collection_rules", "message_limit_reached", "opted_out" ] }, "at_step": { "type": "string", "format": "uuid" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "reason", "at" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "path": { "type": "array", "items": { "type": "object", "properties": { "step_id": { "type": "string", "format": "uuid" }, "step_key": { "type": "string" }, "kind": { "type": "string", "enum": [ "message", "condition", "wait_until", "goto" ] }, "iteration": { "type": "integer", "minimum": 1 }, "at_hours": { "type": [ "number", "null" ] }, "branch": { "type": "string" }, "decided_by": { "type": "string", "enum": [ "scenario", "decision", "default" ] }, "jumped": { "type": "boolean" }, "resolved_by": { "type": "string", "enum": [ "promised_date", "event", "timeout" ] } }, "required": [ "step_id", "step_key", "kind", "iteration", "at_hours" ] }, "description": "Custom sequences with branches, waits until or loops (vitrina-app#6454): every step the person passes, in order, with the branch taken, what ended a wait, and whether a goto jumped." } }, "required": [ "timeline", "end", "notes" ] }, "SequenceSimulateRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid", "description": "A real contact: WhatsApp and opted-out are read from it." }, "persona": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "has_whatsapp": { "type": "boolean" }, "has_email": { "type": "boolean" }, "opted_out": { "type": "boolean" } }, "required": [ "has_whatsapp", "opted_out" ], "description": "A test person. Exactly one of contact_id or persona." }, "last_message_at": { "type": "string", "format": "date-time", "description": "When our last message to the person went out. Default: now." }, "situation": { "type": "string", "enum": [ "conversed", "never_replied", "lost" ], "description": "Which path of «Si no responde». Default: derived from the contact (conversed when they ever wrote), else never_replied." }, "behavior": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "never_replies" ] } }, "required": [ "kind" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "replies_after_step" ] }, "step": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "kind", "step" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pays" ] }, "at_step": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "kind", "at_step" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "promises_date" ] }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "kind", "date" ] } ] }, "version": { "type": "string", "minLength": 1, "maxLength": 80, "description": "`published` (default), `draft` (the open draft) or a version id from `GET /sequences/{id}/versions`." }, "call_outcomes": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/SequenceCallOutcome" }, { "description": "How an AI call step ended: answered | promised_pay | promised_visit | call_later | no_answer | do_not_contact." } ] }, "description": "AI call steps: how each call ends in this scenario, keyed by step id. A call step not named ends `no_answer`. Nothing is called and no model runs; `do_not_contact` ends the walk at that call." }, "decisions": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 60 }, "description": "Custom sequences: the branch each condition takes, `{ : }`. «La IA decide» is never called in a simulation; without an entry it takes its first branch. Other conditions follow `behavior` unless listed here." } }, "required": [ "behavior" ], "additionalProperties": false }, "SequenceDefinitionStep": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "message" ] }, "position": { "type": "integer", "minimum": 1 }, "channel": { "type": "string", "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "fallback_channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "wait": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "duration" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "from": { "type": "string", "enum": [ "previous_step", "start" ] }, "from_step": { "type": [ "string", "null" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "from", "from_step", "hours" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string" } }, "required": [ "type", "event" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agreed_time" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "before_appointment" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "hours" ], "description": "Custom sequences: this long before the booked appointment (a reminder). Only with entry `appointment_booked`." } ] }, "mode": { "type": "string", "enum": [ "auto", "auto_unless_assigned", "approval", "skip" ] }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ai_message" ] }, "template_after_window": { "type": "boolean" } }, "required": [ "type", "template_after_window" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "template_ladder" ] }, "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" } }, "required": [ "name", "language" ] } } }, "required": [ "type", "templates" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "subject": { "type": [ "string", "null" ] }, "custom_body": { "type": "boolean" } }, "required": [ "type", "subject", "custom_body" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "promise" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] } ] }, "config_ref": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "rail": { "type": "string", "enum": [ "unanswered_message", "stalled", "never_replied", "lost" ] }, "step": { "type": "integer" }, "after_hours": { "type": "number" }, "unit": { "type": [ "string", "null" ], "enum": [ "d", "h" ] }, "autonomy": { "type": "string", "enum": [ "auto", "assignee", "approval" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "email", "voice" ] }, "min_score": { "type": [ "number", "null" ] } }, "required": [ "type", "rail", "step", "after_hours", "unit", "autonomy", "channel", "min_score" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "source": { "type": "string" }, "config_origin": { "type": "string", "enum": [ "configured", "inherited", "platform_default" ] } }, "required": [ "type", "source", "config_origin" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "sequence_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "sequence_id" ] }, { "type": "null" } ], "description": "Where a built-in step is stored (keep it as read); null for a step added in the draft." }, "next": { "type": [ "string", "null" ], "maxLength": 120, "description": "Custom sequences: the step key (or `end`) this step goes to; absent/null = the next step by position." } }, "required": [ "key", "situation", "kind", "position", "channel", "fallback_channel", "wait", "mode", "content", "config_ref" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "condition" ] }, "position": { "type": "integer", "minimum": 1 }, "wait": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "duration" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "from": { "type": "string", "enum": [ "previous_step", "start" ] }, "from_step": { "type": [ "string", "null" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "from", "from_step", "hours" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string" } }, "required": [ "type", "event" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agreed_time" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "before_appointment" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "hours" ], "description": "Custom sequences: this long before the booked appointment (a reminder). Only with entry `appointment_booked`." } ] }, "test": { "type": "string", "enum": [ "replied", "paid", "booked", "ai_decides", "call_outcome" ], "description": "`replied` (the customer wrote since our last message), `paid` (unavailable until app#6456), `booked` (an appointment since entering), `ai_decides` (the sequence agent picks a branch; `default_branch` on failure). `call_outcome` (how the latest AI call step ended: one branch per outcome answered | promised_pay | promised_visit | call_later | no_answer | do_not_contact, 2 to 6, the branch key is the outcome; `default_branch` for an outcome with no branch). The fixed tests (replied, paid, booked) have exactly the branches `yes` and `no`." }, "ai_prompt": { "type": [ "string", "null" ], "maxLength": 2000, "default": null }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceBranch" }, "minItems": 1, "maxItems": 6 }, "default_branch": { "type": [ "string", "null" ], "maxLength": 60, "default": null }, "config_ref": { "type": "null" } }, "required": [ "key", "situation", "kind", "position", "wait", "test", "branches" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "wait_until" ] }, "position": { "type": "integer", "minimum": 1 }, "until": { "$ref": "#/components/schemas/SequenceWaitUntil" }, "timeout": { "type": "object", "properties": { "value": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "config_ref": { "type": "null" }, "next": { "type": [ "string", "null" ], "maxLength": 120, "description": "Custom sequences: the step key (or `end`) this step goes to; absent/null = the next step by position." } }, "required": [ "key", "situation", "kind", "position", "until", "timeout" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "goto" ] }, "position": { "type": "integer", "minimum": 1 }, "target_step": { "type": "string", "minLength": 1, "maxLength": 120 }, "max_times": { "type": "integer", "minimum": 1, "maximum": 5, "default": 2, "description": "How many times one person takes this jump (default 2, at most 5)." }, "config_ref": { "type": "null" } }, "required": [ "key", "situation", "kind", "position", "target_step" ] } ], "description": "A step: `message` (any sequence), or — custom sequences only (vitrina-app#6454) — `condition`, `wait_until`, `goto`. A built-in refuses the last three (400)." }, "SequenceDefinition": { "type": "object", "properties": { "schema_version": { "type": "number", "enum": [ 1 ] }, "name": { "type": [ "string", "null" ], "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "entry": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string", "enum": [ "lead_arrived", "customer_went_quiet", "customer_asked_reminder", "stage_changed", "quoted_not_booked", "appointment_booked", "signed_up_not_bought", "installment_overdue" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "maxLength": 40, "description": "Custom sequences filter on `interest`, `source`, `stage` (stage id) or `tag` (tag name)." }, "op": { "type": "string", "enum": [ "in" ] }, "values": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 } }, "required": [ "field", "op", "values" ] }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "days_overdue", "amount" ], "description": "Only for the `installment_overdue` entry: `days_overdue` (days past the due day) or `amount` (pesos still owed), at least `value`." }, "op": { "type": "string", "enum": [ "gte" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "field", "op", "value" ] } ] } } }, "required": [ "type", "event", "filters" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type", "list_id" ] } ] }, "goal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply", "promise_kept", "books_visit", "books_demo", "pays" ] } }, "required": [ "type" ] }, "agent_id": { "type": [ "string", "null" ], "format": "uuid" }, "collection": { "type": "boolean", "description": "Mark the sequence as a collection sequence. Optional (false when left out); an entry of `installment_overdue` or a goal of `pays` makes it one anyway." }, "priority": { "type": "integer" }, "situations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "name": { "type": [ "string", "null" ], "maxLength": 120 }, "enabled": { "type": "boolean" } }, "required": [ "key", "name", "enabled" ] }, "maxItems": 50 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceDefinitionStep" }, "maxItems": 100 }, "connections": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "kind": { "type": "string", "enum": [ "next", "reply_exit", "end", "branch", "loop" ] }, "situation": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ], "description": "Drawn on the arrow (vitrina-app#6454): the branch label, the loop bound, «Después de 2 vueltas»." }, "branch": { "type": [ "string", "null" ], "description": "`branch` connections: the condition branch key." }, "max_times": { "type": [ "integer", "null" ], "description": "`loop` connections: the goto bound." } }, "required": [ "from", "to", "kind", "situation" ] } }, "ends": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "situation": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "mark_lost", "finish", "continue", "handoff" ] }, "after": { "type": [ "object", "null" ], "properties": { "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "continues_in": { "type": [ "object", "null" ], "properties": { "sequence_key": { "type": "string" }, "situation": { "type": [ "string", "null" ] } }, "required": [ "sequence_key", "situation" ] } }, "required": [ "key", "situation", "type", "after", "continues_in" ] } }, "settings": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "config": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "situations": { "type": "object", "properties": { "never_replied": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "lose_after_days": { "type": [ "integer", "null" ] } }, "required": [ "enabled", "lose_after_days" ] }, "stalled": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "lose_after_days": { "type": [ "integer", "null" ] } }, "required": [ "enabled", "lose_after_days" ] }, "lost": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "lose_after_days": { "type": [ "integer", "null" ] } }, "required": [ "enabled", "lose_after_days" ] } }, "required": [ "never_replied", "stalled", "lost" ] }, "unanswered_message": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "conversation_lifetime_cap": { "type": "integer" }, "template_after_window": { "type": "boolean" } }, "required": [ "enabled", "conversation_lifetime_cap", "template_after_window" ] }, "pacing": { "type": "object", "additionalProperties": {} }, "after_handoff": { "type": "object", "additionalProperties": {} } }, "required": [ "enabled", "situations", "unanswered_message", "pacing", "after_handoff" ], "description": "The «Si no responde» settings that are not a step: the same keys as `GET /followups/recontacto` (daily_cap, daily_review_budget, pacing, after_handoff, …), minus the ladders (the steps hold them), the chat reminders’ autonomy (their `mode`) and the platform’s stamps." } }, "required": [ "type", "config" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "daily_cap": { "type": "integer", "minimum": 1 }, "sources": { "type": "object", "additionalProperties": { "type": "object", "properties": { "configured": { "type": "boolean" }, "account_id": { "type": [ "string", "null" ] }, "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "minLength": 1, "maxLength": 20 }, "params": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 20 }, "header_param": { "type": [ "string", "null" ], "maxLength": 80 } }, "required": [ "name", "language", "params", "header_param" ] }, "maxItems": 20 }, "templates_by_intent": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "language": { "type": "string", "minLength": 1, "maxLength": 20 }, "params": { "type": "array", "items": { "type": "string", "maxLength": 80 }, "maxItems": 20 }, "header_param": { "type": [ "string", "null" ], "maxLength": 80 } }, "required": [ "name", "language", "params", "header_param" ] }, "maxItems": 20 } }, "email_account_id": { "type": [ "string", "null" ] }, "email_subject": { "type": [ "string", "null" ], "maxLength": 300 }, "email_body": { "type": [ "string", "null" ], "maxLength": 10000 } }, "required": [ "configured", "account_id", "templates", "templates_by_intent", "email_account_id", "email_subject", "email_body" ] } } }, "required": [ "type", "daily_cap", "sources" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none" ] } }, "required": [ "type" ] } ] } }, "required": [ "schema_version", "name", "description", "entry", "goal", "agent_id", "priority", "situations", "steps", "connections", "ends", "settings" ] }, "SequenceDefinitionView": { "type": "object", "properties": { "sequence_id": { "type": "string", "format": "uuid" }, "sequence_key": { "type": "string" }, "version_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Null for the published version of a built-in that was never versioned (today’s config)." }, "version": { "type": [ "integer", "null" ], "description": "Null for a draft (numbered on publish) or when unversioned." }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "definition": { "$ref": "#/components/schemas/SequenceDefinition" } }, "required": [ "sequence_id", "sequence_key", "version_id", "version", "status", "definition" ] }, "SequenceDraft": { "type": "object", "properties": { "sequence_id": { "type": "string", "format": "uuid" }, "sequence_key": { "type": "string" }, "version_id": { "type": "string", "format": "uuid" }, "based_on_version": { "type": [ "integer", "null" ] }, "change_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, "updated_by": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, "definition": { "$ref": "#/components/schemas/SequenceDefinition" }, "sequence": { "$ref": "#/components/schemas/Sequence" } }, "required": [ "sequence_id", "sequence_key", "version_id", "based_on_version", "change_count", "created_at", "updated_at", "created_by", "updated_by", "definition", "sequence" ] }, "SequenceChange": { "type": "object", "properties": { "field": { "type": "string", "description": "Dotted address: `steps.stalled-2.wait`, `situations.lost.enabled`, `settings.pacing.max_per_day`." }, "kind": { "type": "string", "enum": [ "added", "removed", "changed" ] }, "step_key": { "type": [ "string", "null" ] }, "situation": { "type": [ "string", "null" ] }, "before": {}, "after": {}, "people_affected_now": { "type": [ "integer", "null" ], "description": "People at that step (or in that situation, or in the sequence) right now; null when the sequence keeps no count («Al llegar»)." } }, "required": [ "field", "kind", "step_key", "situation", "people_affected_now" ] }, "SequenceDraftDiff": { "type": "object", "properties": { "sequence_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "base_version": { "type": [ "integer", "null" ] }, "change_count": { "type": "integer" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceChange" } } }, "required": [ "sequence_id", "version_id", "base_version", "change_count", "changes" ] }, "SequenceValidationProblem": { "type": "object", "properties": { "code": { "type": "string" }, "step_id": { "type": [ "string", "null" ] }, "message": { "type": "string" }, "fix": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "draft_template", "connect_channel", "request_review", "remove_step", "change_channel", "pick_agent", "contact_support" ] }, "target": { "$ref": "#/components/schemas/NotificationTarget" } }, "required": [ "kind" ] } }, "required": [ "code", "step_id", "message", "fix" ] }, "SequenceDraftValidation": { "type": "object", "properties": { "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceValidationProblem" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceValidationProblem" } } }, "required": [ "blockers", "warnings" ] }, "CollectionRules": { "type": "object", "properties": { "weekdays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "minItems": 1, "maxItems": 7, "description": "Days collection may contact, ISO (1 = Monday … 7 = Sunday). Sunday is never allowed." }, "hours": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ], "description": "Local window (workspace time zone), start inclusive, end exclusive." }, "skip_holidays": { "type": "boolean", "description": "National public holidays never allow a contact. Must be true." }, "calls_per_day": { "type": "integer", "minimum": 0, "maximum": 10 }, "calls_per_week": { "type": "integer", "minimum": 0, "maximum": 10 }, "messages_per_week": { "type": "integer", "minimum": 0, "maximum": 14 }, "min_spacing_hours": { "type": "integer", "minimum": 0, "maximum": 720 }, "over_cap": { "type": "string", "enum": [ "skip", "move" ], "description": "`skip` drops a step that would go over a cap; `move` pushes it to the next week." } }, "required": [ "weekdays", "hours", "skip_holidays", "calls_per_day", "calls_per_week", "messages_per_week", "min_spacing_hours", "over_cap" ] }, "CollectionRulesView": { "type": "object", "properties": { "rules": { "$ref": "#/components/schemas/CollectionRules" }, "version": { "type": "integer", "description": "0 = the platform defaults, never saved. Goes up on every real change; a legal review names the version it reviewed." }, "is_default": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ] }, "updated_by": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, "ceilings": { "type": "object", "properties": { "weekdays": { "type": "array", "items": { "type": "integer" } }, "hours": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ] }, "calls_per_day": { "type": "integer" }, "calls_per_week": { "type": "integer" }, "messages_per_week": { "type": "integer" }, "min_spacing_hours": { "type": "integer" } }, "required": [ "weekdays", "hours", "calls_per_day", "calls_per_week", "messages_per_week", "min_spacing_hours" ] } }, "required": [ "rules", "version", "is_default", "updated_at", "updated_by", "ceilings" ] }, "CollectionRulesReplaceRequest": { "type": "object", "properties": { "weekdays": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 7 }, "minItems": 1, "maxItems": 7, "description": "Days collection may contact, ISO (1 = Monday … 7 = Sunday). Sunday is never allowed." }, "hours": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "end": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "start", "end" ], "description": "Local window (workspace time zone), start inclusive, end exclusive." }, "skip_holidays": { "type": "boolean", "description": "National public holidays never allow a contact. Must be true." }, "calls_per_day": { "type": "integer", "minimum": 0, "maximum": 10 }, "calls_per_week": { "type": "integer", "minimum": 0, "maximum": 10 }, "messages_per_week": { "type": "integer", "minimum": 0, "maximum": 14 }, "min_spacing_hours": { "type": "integer", "minimum": 0, "maximum": 720 }, "over_cap": { "type": "string", "enum": [ "skip", "move" ], "description": "`skip` drops a step that would go over a cap; `move` pushes it to the next week." } }, "additionalProperties": false }, "SequenceLegalReview": { "type": "object", "properties": { "sequence_id": { "type": "string", "format": "uuid" }, "required": { "type": "boolean", "description": "True for a collection sequence." }, "status": { "type": "string", "enum": [ "not_required", "missing", "valid", "outdated" ] }, "rules_version": { "type": "integer" }, "review": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "reviewer_member_id": { "type": "string", "format": "uuid" }, "reviewed_on": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "attachment_url": { "type": [ "string", "null" ] }, "rules_version": { "type": "integer" }, "created_at": { "type": "string" }, "created_by": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] } }, "required": [ "id", "reviewer_member_id", "reviewed_on", "note", "attachment_url", "rules_version", "created_at", "created_by" ] } }, "required": [ "sequence_id", "required", "status", "rules_version", "review" ] }, "SequenceLegalReviewRequest": { "type": "object", "properties": { "reviewer_member_id": { "type": "string", "format": "uuid" }, "reviewed_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Day of the review (YYYY-MM-DD). Default today; not in the future." }, "note": { "type": [ "string", "null" ], "maxLength": 4000 }, "attachment_url": { "type": [ "string", "null" ], "maxLength": 2000, "format": "uri" }, "rules_version": { "type": "integer", "minimum": 0, "description": "The rules version the reviewer looked at. 409 `rules_version_stale` when the rules changed since; default the current version." } }, "required": [ "reviewer_member_id" ], "additionalProperties": false }, "SequencePublishResult": { "type": "object", "properties": { "sequence_id": { "type": "string", "format": "uuid" }, "version_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "published_at": { "type": "string" }, "origin": { "type": "string", "enum": [ "edit", "revert", "materialized", "external" ] }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceChange" } }, "sequence": { "$ref": "#/components/schemas/Sequence" } }, "required": [ "sequence_id", "version_id", "version", "published_at", "origin", "changes", "sequence" ] }, "SequenceVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "origin": { "type": "string", "enum": [ "edit", "revert", "materialized", "external" ] }, "based_on_version": { "type": [ "integer", "null" ] }, "reverted_from": { "type": [ "integer", "null" ] }, "change_count": { "type": "integer" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceChange" } }, "created_at": { "type": "string" }, "created_by": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, "published_at": { "type": [ "string", "null" ] }, "published_by": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] } }, "required": [ "id", "version", "status", "origin", "based_on_version", "reverted_from", "change_count", "changes", "created_at", "created_by", "published_at", "published_by" ] }, "SequenceTemplate": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "blank", "quote_followup", "reactivate", "signup_not_paid", "installments", "appointment_reminder" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "entry": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string", "enum": [ "lead_arrived", "customer_went_quiet", "customer_asked_reminder", "stage_changed", "quoted_not_booked", "appointment_booked", "signed_up_not_bought", "installment_overdue" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "maxLength": 40, "description": "Custom sequences filter on `interest`, `source`, `stage` (stage id) or `tag` (tag name)." }, "op": { "type": "string", "enum": [ "in" ] }, "values": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 } }, "required": [ "field", "op", "values" ] }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "days_overdue", "amount" ], "description": "Only for the `installment_overdue` entry: `days_overdue` (days past the due day) or `amount` (pesos still owed), at least `value`." }, "op": { "type": "string", "enum": [ "gte" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "field", "op", "value" ] } ] } } }, "required": [ "type", "event", "filters" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type", "list_id" ] } ] }, "goal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply", "promise_kept", "books_visit", "books_demo", "pays" ] }, "label": { "type": "string" } }, "required": [ "type", "label" ] }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] } }, "steps": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "message" ] }, "position": { "type": "integer", "minimum": 1 }, "channel": { "type": "string", "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "fallback_channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "same_chat", "instagram", "email", "call", "sms" ] }, "wait": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "duration" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "from": { "type": "string", "enum": [ "previous_step", "start" ] }, "from_step": { "type": [ "string", "null" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "from", "from_step", "hours" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string" } }, "required": [ "type", "event" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agreed_time" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "before_appointment" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "hours" ], "description": "Custom sequences: this long before the booked appointment (a reminder). Only with entry `appointment_booked`." } ] }, "mode": { "type": "string", "enum": [ "auto", "auto_unless_assigned", "approval", "skip" ] }, "content": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ai_message" ] }, "template_after_window": { "type": "boolean" } }, "required": [ "type", "template_after_window" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "template_ladder" ] }, "templates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "language": { "type": "string" } }, "required": [ "name", "language" ] } } }, "required": [ "type", "templates" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "email" ] }, "subject": { "type": [ "string", "null" ] }, "custom_body": { "type": "boolean" } }, "required": [ "type", "subject", "custom_body" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "promise" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] } ] }, "config_ref": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recontacto" ] }, "rail": { "type": "string", "enum": [ "unanswered_message", "stalled", "never_replied", "lost" ] }, "step": { "type": "integer" }, "after_hours": { "type": "number" }, "unit": { "type": [ "string", "null" ], "enum": [ "d", "h" ] }, "autonomy": { "type": "string", "enum": [ "auto", "assignee", "approval" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "instagram", "email", "voice" ] }, "min_score": { "type": [ "number", "null" ] } }, "required": [ "type", "rail", "step", "after_hours", "unit", "autonomy", "channel", "min_score" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "first_touch" ] }, "source": { "type": "string" }, "config_origin": { "type": "string", "enum": [ "configured", "inherited", "platform_default" ] } }, "required": [ "type", "source", "config_origin" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "followup" ] }, "followup_id": { "type": "string", "format": "uuid" }, "trigger_key": { "type": "string" } }, "required": [ "type", "followup_id", "trigger_key" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "sequence_id": { "type": "string", "format": "uuid" } }, "required": [ "type", "sequence_id" ] }, { "type": "null" } ], "description": "Where a built-in step is stored (keep it as read); null for a step added in the draft." }, "next": { "type": [ "string", "null" ], "maxLength": 120, "description": "Custom sequences: the step key (or `end`) this step goes to; absent/null = the next step by position." }, "label": { "type": "string" } }, "required": [ "key", "situation", "kind", "position", "channel", "fallback_channel", "wait", "mode", "content", "config_ref", "label" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "condition" ] }, "position": { "type": "integer", "minimum": 1 }, "wait": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "duration" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "from": { "type": "string", "enum": [ "previous_step", "start" ] }, "from_step": { "type": [ "string", "null" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "from", "from_step", "hours" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string" } }, "required": [ "type", "event" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agreed_time" ] } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "before_appointment" ] }, "value": { "type": "number" }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] }, "hours": { "type": "number" } }, "required": [ "type", "value", "unit", "hours" ], "description": "Custom sequences: this long before the booked appointment (a reminder). Only with entry `appointment_booked`." } ] }, "test": { "type": "string", "enum": [ "replied", "paid", "booked", "ai_decides", "call_outcome" ], "description": "`replied` (the customer wrote since our last message), `paid` (unavailable until app#6456), `booked` (an appointment since entering), `ai_decides` (the sequence agent picks a branch; `default_branch` on failure). `call_outcome` (how the latest AI call step ended: one branch per outcome answered | promised_pay | promised_visit | call_later | no_answer | do_not_contact, 2 to 6, the branch key is the outcome; `default_branch` for an outcome with no branch). The fixed tests (replied, paid, booked) have exactly the branches `yes` and `no`." }, "ai_prompt": { "type": [ "string", "null" ], "maxLength": 2000, "default": null }, "branches": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceBranch" }, "minItems": 1, "maxItems": 6 }, "default_branch": { "type": [ "string", "null" ], "maxLength": 60, "default": null }, "config_ref": { "type": "null" }, "label": { "type": "string" } }, "required": [ "key", "situation", "kind", "position", "wait", "test", "branches", "label" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "wait_until" ] }, "position": { "type": "integer", "minimum": 1 }, "until": { "$ref": "#/components/schemas/SequenceWaitUntil" }, "timeout": { "type": "object", "properties": { "value": { "type": "number", "exclusiveMinimum": 0, "maximum": 2160 }, "unit": { "type": "string", "enum": [ "minutes", "hours", "days" ] } }, "required": [ "value", "unit" ] }, "config_ref": { "type": "null" }, "next": { "type": [ "string", "null" ], "maxLength": 120, "description": "Custom sequences: the step key (or `end`) this step goes to; absent/null = the next step by position." }, "label": { "type": "string" } }, "required": [ "key", "situation", "kind", "position", "until", "timeout", "label" ] }, { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 120 }, "situation": { "type": [ "string", "null" ], "maxLength": 120 }, "kind": { "type": "string", "enum": [ "goto" ] }, "position": { "type": "integer", "minimum": 1 }, "target_step": { "type": "string", "minLength": 1, "maxLength": 120 }, "max_times": { "type": "integer", "minimum": 1, "maximum": 5, "default": 2, "description": "How many times one person takes this jump (default 2, at most 5)." }, "config_ref": { "type": "null" }, "label": { "type": "string" } }, "required": [ "key", "situation", "kind", "position", "target_step", "label" ] } ] } } }, "required": [ "key", "name", "description", "entry", "goal", "channels", "steps" ] }, "SequenceCreateResult": { "type": "object", "properties": { "sequence": { "$ref": "#/components/schemas/Sequence" }, "draft": { "$ref": "#/components/schemas/SequenceDraft" } }, "required": [ "sequence", "draft" ] }, "SequenceCreateRequest": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "blank", "quote_followup", "reactivate", "signup_not_paid", "installments", "appointment_reminder" ], "description": "A template from `GET /sequences/templates` (its suggested steps become the first draft); omitted = `blank` (from scratch)." }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "entry": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string", "enum": [ "lead_arrived", "customer_went_quiet", "customer_asked_reminder", "stage_changed", "quoted_not_booked", "appointment_booked", "signed_up_not_bought", "installment_overdue" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "maxLength": 40, "description": "Custom sequences filter on `interest`, `source`, `stage` (stage id) or `tag` (tag name)." }, "op": { "type": "string", "enum": [ "in" ] }, "values": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 } }, "required": [ "field", "op", "values" ] }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "days_overdue", "amount" ], "description": "Only for the `installment_overdue` entry: `days_overdue` (days past the due day) or `amount` (pesos still owed), at least `value`." }, "op": { "type": "string", "enum": [ "gte" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "field", "op", "value" ] } ] } } }, "required": [ "type", "event", "filters" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type", "list_id" ] } ] }, "goal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply", "promise_kept", "books_visit", "books_demo", "pays" ] } }, "required": [ "type" ] }, "agent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The AI agent that runs this sequence: writes its messages with its own persona and knowledge, and answers when the person replies. Must be an active agent of the workspace. `null` = the workspace's current agent." } }, "additionalProperties": false }, "SequencePatchRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "entry": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "event" ] }, "event": { "type": "string", "enum": [ "lead_arrived", "customer_went_quiet", "customer_asked_reminder", "stage_changed", "quoted_not_booked", "appointment_booked", "signed_up_not_bought", "installment_overdue" ] }, "filters": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "field": { "type": "string", "maxLength": 40, "description": "Custom sequences filter on `interest`, `source`, `stage` (stage id) or `tag` (tag name)." }, "op": { "type": "string", "enum": [ "in" ] }, "values": { "type": "array", "items": { "type": "string", "maxLength": 200 }, "maxItems": 50 } }, "required": [ "field", "op", "values" ] }, { "type": "object", "properties": { "field": { "type": "string", "enum": [ "days_overdue", "amount" ], "description": "Only for the `installment_overdue` entry: `days_overdue` (days past the due day) or `amount` (pesos still owed), at least `value`." }, "op": { "type": "string", "enum": [ "gte" ] }, "value": { "type": "number", "minimum": 0, "maximum": 1000000000 } }, "required": [ "field", "op", "value" ] } ] } } }, "required": [ "type", "event", "filters" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "list" ] }, "list_id": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "type", "list_id" ] } ] }, "goal": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "reply", "promise_kept", "books_visit", "books_demo", "pays" ] } }, "required": [ "type" ] }, "agent_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The AI agent that runs this sequence: writes its messages with its own persona and knowledge, and answers when the person replies. Must be an active agent of the workspace. `null` = the workspace's current agent." } }, "additionalProperties": false }, "SequenceDeleteResult": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "exited": { "type": "integer" } }, "required": [ "deleted", "exited" ] }, "SequenceOrder": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "priority": { "type": "integer" } }, "required": [ "id", "key", "priority" ] } } }, "required": [ "order" ] }, "SequenceOrderRequest": { "type": "object", "properties": { "order": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1, "maxItems": 500, "description": "Highest priority first: `builtin:si-no-responde` and every custom sequence id, each exactly once." } }, "required": [ "order" ], "additionalProperties": false }, "SequenceEnrollmentPromise": { "type": "object", "properties": { "enrollment_id": { "type": "string", "format": "uuid" }, "sequence_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "promised_date": { "type": [ "string", "null" ] }, "current_step": { "type": [ "string", "null" ], "description": "The step key the person is at." }, "next_due_at": { "type": [ "string", "null" ] }, "waiting_for_date": { "type": "boolean", "description": "True when the person is at a «Esperar hasta la fecha prometida» step (it now waits for this date)." } }, "required": [ "enrollment_id", "sequence_id", "contact_id", "promised_date", "current_step", "next_due_at", "waiting_for_date" ] }, "SequencePromisedDateRequest": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The day the customer promised (`YYYY-MM-DD`, workspace calendar); null clears it.", "example": "2026-11-15" } }, "required": [ "date" ], "additionalProperties": false }, "SequenceEnrollmentFunnel": { "type": "object", "properties": { "total": { "type": "integer" }, "reachable": { "type": "integer" }, "will_enroll": { "type": "integer" }, "excluded": { "type": "object", "properties": { "blocked": { "type": "integer" }, "spam": { "type": "integer" }, "archived": { "type": "integer" }, "no_identifier": { "type": "integer" }, "invalid_identifier": { "type": "integer" }, "duplicate": { "type": "integer" }, "opted_out": { "type": "integer" }, "already_in_sequence": { "type": "integer" }, "in_higher_sequence": { "type": "integer" }, "in_lower_sequence": { "type": "integer" }, "in_recontacto": { "type": "integer" } }, "required": [ "blocked", "spam", "archived", "no_identifier", "invalid_identifier", "duplicate", "opted_out", "already_in_sequence", "in_higher_sequence", "in_lower_sequence", "in_recontacto" ] }, "opted_out_by": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "total", "reachable", "will_enroll", "excluded", "opted_out_by" ] }, "SequenceEnrollmentBatch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequence_id": { "type": "string", "format": "uuid" }, "list_id": { "type": "string", "format": "uuid" }, "list_name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending_activation", "activated", "cancelled" ] }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "consent": { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "customer_relationship", "explicit_opt_in", "other_documented" ], "description": "Why the owner may write to this list: `customer_relationship` (past or current customers), `explicit_opt_in` (they registered and accepted terms, or consented in a form), `other_documented` (anything else, described in the note)." }, "note": { "type": "string" }, "by": { "type": "object", "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] } }, "required": [ "kind", "id", "via" ] }, "at": { "type": "string" } }, "required": [ "basis", "note", "by", "at" ] }, "funnel": { "$ref": "#/components/schemas/SequenceEnrollmentFunnel" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "whatsapp_marketing_cost" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "result": { "allOf": [ { "$ref": "#/components/schemas/SequenceEnrollmentFunnel" }, { "type": [ "object", "null" ], "properties": { "enrolled": { "type": "integer" } }, "required": [ "enrolled" ] } ] }, "activated_at": { "type": [ "string", "null" ] }, "activated_by": { "type": [ "object", "null" ], "properties": { "kind": { "type": [ "string", "null" ] }, "id": { "type": [ "string", "null" ] } }, "required": [ "kind", "id" ] }, "created_at": { "type": "string" } }, "required": [ "id", "sequence_id", "list_id", "list_name", "status", "channel", "consent", "funnel", "warnings", "result", "activated_at", "activated_by", "created_at" ] }, "SequenceEnrollFromListRequest": { "type": "object", "properties": { "list_id": { "type": "string", "format": "uuid", "description": "The list to enroll: the id of a saved audience (`GET /audiences`). A CSV import becomes a list by importing with `tags` and saving an audience on that tag." }, "consent_basis": { "type": "string", "enum": [ "customer_relationship", "explicit_opt_in", "other_documented" ], "description": "Why the owner may write to this list: `customer_relationship` (past or current customers), `explicit_opt_in` (they registered and accepted terms, or consented in a form), `other_documented` (anything else, described in the note)." }, "note": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Evidence of the consent: where and when it was given. Stored with who and when." } }, "required": [ "list_id", "consent_basis", "note" ], "additionalProperties": false }, "SequenceEnrollment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequence_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "active", "exited", "completed" ] }, "exit_reason": { "type": [ "string", "null" ] }, "entered_at": { "type": "string" }, "exited_at": { "type": [ "string", "null" ] }, "batch_id": { "type": [ "string", "null" ], "format": "uuid" }, "consent": { "type": [ "object", "null" ], "properties": { "basis": { "type": "string", "enum": [ "customer_relationship", "explicit_opt_in", "other_documented" ], "description": "Why the owner may write to this list: `customer_relationship` (past or current customers), `explicit_opt_in` (they registered and accepted terms, or consented in a form), `other_documented` (anything else, described in the note)." }, "note": { "type": [ "string", "null" ] }, "at": { "type": [ "string", "null" ] } }, "required": [ "basis", "note", "at" ] } }, "required": [ "id", "sequence_id", "contact_id", "status", "exit_reason", "entered_at", "exited_at", "batch_id", "consent" ] }, "MetaAdsAccount": { "type": [ "object", "null" ], "properties": { "external_account_id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "delivers_spend": { "type": "boolean" }, "provider_connection_id": { "type": "string", "format": "uuid", "description": "The id of the provider connection this ad account ships through. Opaque; Vitrina resolves it server-side for every Ads read and write, so a client never needs to send it back." }, "atribu_connection_id": { "type": "string", "description": "Deprecated: the same value as `provider_connection_id` — read that instead. Kept on the wire for existing clients; removed in a later release.", "deprecated": true } }, "required": [ "external_account_id", "name", "currency", "timezone", "delivers_spend", "provider_connection_id", "atribu_connection_id" ] }, "MetaAdsCandidate": { "type": "object", "properties": { "candidate_id": { "type": "string" }, "external_account_id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "account_status": { "type": "string" }, "timezone": { "type": [ "string", "null" ] } }, "required": [ "candidate_id", "external_account_id", "name", "currency", "account_status", "timezone" ] }, "MetaAdsIntegration": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string", "enum": [ "meta_ads" ] }, "status": { "type": "string", "enum": [ "pending", "pending_selection", "connected", "error", "disconnected" ] }, "account_label": { "type": [ "string", "null" ] }, "connected_at": { "type": [ "string", "null" ] }, "disconnected_at": { "type": [ "string", "null" ], "description": "When the connection last stopped being `connected` (disconnected, access revoked, or the token stopped working) — the last day the ad figures are current («cifras hasta el …»). `null` while `connected`, when it was never connected, and for a stop recorded before this field existed." }, "account": { "$ref": "#/components/schemas/MetaAdsAccount" }, "error": { "type": [ "object", "null" ], "properties": { "reason": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "reason", "retryable" ] }, "handoff": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "id", "expires_at" ] }, "candidates": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/MetaAdsCandidate" } }, "updated_at": { "type": "string" } }, "required": [ "id", "provider", "status", "account_label", "connected_at", "disconnected_at", "account", "error", "handoff", "candidates", "updated_at" ] }, "MetaAdsConnectResult": { "type": "object", "properties": { "url": { "type": "string" }, "handoff_id": { "type": "string" }, "expires_at": { "type": "string" } }, "required": [ "url", "handoff_id", "expires_at" ] }, "MetaAdsConnectBody": { "type": "object", "properties": { "return_to": { "type": "string", "format": "uri" } }, "required": [ "return_to" ] }, "MetaAdsReturnBody": { "type": "object", "properties": { "handoff_id": { "type": "string", "minLength": 1 }, "state": { "type": "string", "minLength": 1 } } }, "MetaAdsFinalizeBody": { "type": "object", "properties": { "candidate_id": { "type": "string", "minLength": 1 } }, "required": [ "candidate_id" ] }, "MetaAdsPage": { "type": "object", "properties": { "page_external_id": { "type": "string" }, "name": { "type": "string" }, "picture_url": { "type": [ "string", "null" ] }, "instagram_username": { "type": [ "string", "null" ] } }, "required": [ "page_external_id", "name", "picture_url", "instagram_username" ] }, "MetaAdsAvailablePage": { "allOf": [ { "$ref": "#/components/schemas/MetaAdsPage" }, { "type": "object", "properties": { "connected": { "type": "boolean" } }, "required": [ "connected" ] } ] }, "MetaAdsPagesState": { "type": "object", "properties": { "available": { "type": "array", "items": { "$ref": "#/components/schemas/MetaAdsAvailablePage" }, "description": "Every Facebook Page the connected Meta account can see, with whether it is already tracked. Empty while `needs_reconsent`." }, "connected": { "type": "array", "items": { "$ref": "#/components/schemas/MetaAdsPage" }, "description": "The Pages currently tracked, even while `needs_reconsent`." }, "needs_reconsent": { "type": "boolean", "description": "The Meta grant lacks the Page permissions (or Meta no longer accepts it). Restart `POST /integrations/meta-ads/connect`: the consent asks for them again." }, "reconsent_reason": { "type": [ "string", "null" ], "enum": [ "missing_scopes", "token_invalid" ] } }, "required": [ "available", "connected", "needs_reconsent", "reconsent_reason" ] }, "MetaAdsSetPagesResult": { "type": "object", "properties": { "enabled_count": { "type": "integer" }, "unavailable_page_external_ids": { "type": "array", "items": { "type": "string" }, "description": "Requested Pages the Meta account cannot see; not saved." } }, "required": [ "enabled_count", "unavailable_page_external_ids" ] }, "MetaAdsSetPagesBody": { "type": "object", "properties": { "page_external_ids": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "The Pages to track — exactly this set. Pages left out stop being tracked; an empty list stops tracking all of them." } }, "required": [ "page_external_ids" ] }, "MetaAdsAdsNotConnected": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "not_connected" ] }, "reason": { "type": "string", "enum": [ "whatsapp_not_connected" ] } }, "required": [ "state" ] }, "MetaAdsAdGreeting": { "type": [ "object", "null" ], "properties": { "text": { "type": [ "string", "null" ] }, "autofill_message": { "type": [ "string", "null" ] }, "ice_breakers": { "type": "array", "items": { "type": "string" } }, "landing_screen_type": { "type": [ "string", "null" ] } }, "required": [ "text", "autofill_message", "ice_breakers", "landing_screen_type" ] }, "MetaAdsAdRow": { "type": "object", "properties": { "ad_id": { "type": "string" }, "ad_name": { "type": "string" }, "ad_status": { "type": "string" }, "campaign": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "ad_set": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "destination": { "type": "object", "properties": { "type": { "type": "string" }, "whatsapp_phone_number": { "type": [ "string", "null" ] }, "page_id": { "type": [ "string", "null" ] } }, "required": [ "type", "whatsapp_phone_number", "page_id" ] }, "cta_type": { "type": [ "string", "null" ] }, "greeting": { "$ref": "#/components/schemas/MetaAdsAdGreeting" }, "greeting_status": { "type": "string", "enum": [ "present", "none", "unreadable" ] }, "checks": { "type": "object", "properties": { "destination_connected": { "type": [ "boolean", "null" ] }, "greeting_configured": { "type": "boolean" } }, "required": [ "destination_connected", "greeting_configured" ] }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "ad_id", "ad_name", "ad_status", "campaign", "ad_set", "destination", "cta_type", "greeting", "greeting_status", "checks", "last_synced_at" ] }, "MetaAdsAdsConnected": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "connected" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MetaAdsAdRow" } }, "next_cursor": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ] } }, "required": [ "state", "items", "next_cursor", "last_synced_at" ] }, "MetaAdsAdsResponse": { "anyOf": [ { "$ref": "#/components/schemas/MetaAdsAdsNotConnected" }, { "$ref": "#/components/schemas/MetaAdsAdsConnected" } ] }, "WooCommerceConnectBody": { "type": "object", "properties": { "store_url": { "type": "string", "minLength": 3, "maxLength": 500 }, "return_to": { "type": "string", "format": "uri" } }, "required": [ "store_url" ] }, "WooCommerceSyncBody": { "type": "object", "properties": { "force": { "type": "boolean" } } }, "ExternalStockSourceBody": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048, "format": "uri" }, "token": { "type": "string", "minLength": 8, "maxLength": 512 } }, "required": [ "url" ] }, "ProviderConnectionAccount": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string", "description": "The provider’s own id for the account (GoHighLevel location id, Mercado Pago user id). Opaque; relayed verbatim." }, "name": { "type": "string", "description": "The account’s display name at the provider." } }, "required": [ "external_id", "name" ], "description": "The connected account. Present on `connected` and `needs_reconnect` (the card must name what needs reconnecting)." }, "ProviderConnectionReason": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "user_cancelled", "provider_denied", "provider_error", "token_exchange_failed", "account_connected_elsewhere", "no_candidates", "connect_failed", "internal_error", "state_expired", "state_invalid", "handoff_expired", "handoff_used", "provider_not_configured", "origin_not_allowed", "selection_expired", "selection_conflict", "reconnect_required", "sync_error", "access_revoked", "disconnected_by_user", "connection_not_found", "handoff_not_found", "unknown_error" ], "description": "A STABLE code — also the copy key. `user_cancelled`, `provider_denied`, `provider_error`, `token_exchange_failed`, `account_connected_elsewhere`, `no_candidates`, `connect_failed`, `internal_error`, `state_expired`, `state_invalid`, `handoff_expired`, `handoff_used`, `provider_not_configured`, `origin_not_allowed` come from the consent itself; `selection_expired`, `selection_conflict`, `reconnect_required`, `sync_error`, `access_revoked`, `disconnected_by_user`, `connection_not_found`, `handoff_not_found`, `unknown_error` are Vitrina’s own." }, "label": { "type": "string", "description": "A ready Spanish sentence for the card, naming the provider." }, "retryable": { "type": "boolean", "description": "Is trying the same thing again, right away, likely to work?" } }, "required": [ "code", "label", "retryable" ], "description": "Why the card is in this state: a failed first connect, `reconnect_required`, `sync_error` (connected, last sync failed), `access_revoked`, `disconnected_by_user`." }, "ProviderConnection": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "gohighlevel", "mercadopago", "shopify" ] }, "display_name": { "type": "string" }, "category": { "type": "string", "enum": [ "crm", "payments", "commerce" ] }, "description": { "type": "string", "description": "One sentence: what connecting it does for the workspace." }, "state": { "type": "string", "enum": [ "not_connected", "connecting", "connected", "needs_reconnect", "disconnected" ], "description": "`not_connected` (never connected) → `connecting` (first consent in flight) → `connected` → `needs_reconnect` (the provider stopped honouring the grant; data is not updating) → `disconnected` (was connected, is not any more)." }, "state_label": { "type": "string", "description": "The state in Spanish, ready to render." }, "account": { "$ref": "#/components/schemas/ProviderConnectionAccount" }, "last_account": { "allOf": [ { "$ref": "#/components/schemas/ProviderConnectionAccount" }, { "description": "On `disconnected`: the account that was connected." } ] }, "reason": { "$ref": "#/components/schemas/ProviderConnectionReason" }, "last_attempt": { "allOf": [ { "$ref": "#/components/schemas/ProviderConnectionReason" }, { "description": "How the latest attempt ended when it left the state unchanged (a cancelled re-authorization of a connected or needs_reconnect card). A secondary note; `reason` keeps saying why the card is in its state." } ] }, "next_step": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "connect", "resume", "choose_account", "reconnect", "retry", "activate_addon", "contact_support", "none" ], "description": "`connect` / `resume` / `reconnect` / `retry` → `POST …/connect`; `activate_addon` → the Vitrina Ads add-on; `choose_account` → `POST …/finalize`; `contact_support` and `none` call nothing. Disconnect is always available on a card that is not `not_connected`." }, "label": { "type": [ "string", "null" ], "description": "The primary button’s label, or null for `none`." } }, "required": [ "action", "label" ], "description": "The one thing the card should offer next. Never a dead end." }, "attempt": { "type": [ "object", "null" ], "properties": { "step": { "type": "string", "enum": [ "consent", "choose_account" ] }, "handoff": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string" } }, "required": [ "id", "expires_at" ], "description": "The consent this attempt belongs to. On `choose_account`, send its `id` to `/finalize` as `handoff_id`." }, "candidates": { "type": [ "array", "null" ], "items": { "allOf": [ { "$ref": "#/components/schemas/ProviderConnectionAccount" }, { "type": "object" } ] }, "description": "Step `choose_account` only: the accounts the consent can connect. Send one `external_id` to `/finalize`." }, "selection_expires_at": { "type": [ "string", "null" ] }, "prompt": { "type": "string", "description": "The picker / waiting title, in Spanish." } }, "required": [ "step", "handoff", "candidates", "selection_expires_at", "prompt" ], "description": "A connect in flight, if any — a consent the admin is on, or an account choice still owed. Rides on top of `state`: reconnecting a connected account does not make the card read `connecting`." }, "connected_at": { "type": [ "string", "null" ] }, "disconnected_at": { "type": [ "string", "null" ] }, "last_synced_at": { "type": [ "string", "null" ], "description": "When the provider’s data last finished syncing." }, "updated_at": { "type": [ "string", "null" ] }, "connect_input": { "type": "string", "enum": [ "none", "shop" ], "description": "What `POST …/connect` must carry besides `return_to`: `shop` for Shopify (the store’s address), `none` for every other provider." }, "connect_notice": { "type": [ "string", "null" ], "description": "Show this BEFORE sending the page to the provider, or null. Shopify: its consent screen names the connectivity partner’s app, not Vitrina; saying so first keeps the merchant from abandoning the install there. A ready Spanish paragraph." }, "catalog": { "type": [ "object", "null" ], "properties": { "product_count": { "type": [ "number", "null" ], "description": "Products Vitrina offers from the store after the last sync." }, "variant_count": { "type": [ "number", "null" ] }, "last_sync_at": { "type": [ "string", "null" ], "description": "When the last import, reconcile or stock update finished." }, "last_sync_kind": { "type": [ "string", "null" ], "enum": [ "full", "delta" ], "description": "`full` — a walk of the whole store (import, hourly reconcile, «Sincronizar ahora»); `delta` — the products the store changed, pulled seconds after the change." }, "last_sync_status": { "type": [ "string", "null" ], "enum": [ "running", "success", "blocked", "error" ], "description": "`blocked`: the reconcile found many products gone at once and switched none off (the drop guard); `POST …/sync {force:true}` applies it when the store really was emptied." }, "last_sync_error": { "type": [ "string", "null" ], "description": "A ready Spanish sentence when the last run did not apply." }, "last_sync_summary": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Counters of the last run (products, variants, deactivated…)." }, "last_full_sync_at": { "type": [ "string", "null" ] } }, "required": [ "product_count", "variant_count", "last_sync_at", "last_sync_kind", "last_sync_status", "last_sync_error", "last_sync_summary", "last_full_sync_at" ], "description": "A store (`category: commerce`): its catalog as Vitrina keeps it. Null on every other card." }, "addon_active": { "type": "boolean", "description": "Whether the Vitrina Ads add-on is active. `false` only on a card that outlived a lapsed add-on (a connection or a consent in flight): it stays visible and can be disconnected, and any step that would start a new consent becomes `activate_addon`." } }, "required": [ "provider", "display_name", "category", "description", "state", "state_label", "account", "last_account", "reason", "last_attempt", "next_step", "attempt", "connected_at", "disconnected_at", "last_synced_at", "updated_at", "connect_input", "connect_notice", "catalog", "addon_active" ] }, "ProviderConnectResult": { "type": "object", "properties": { "url": { "type": "string", "description": "Send the WHOLE page here: it goes straight to the provider’s consent screen. Single-use, 45 minutes." }, "handoff_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string" }, "connection": { "$ref": "#/components/schemas/ProviderConnection" } }, "required": [ "url", "handoff_id", "expires_at", "connection" ] }, "ProviderConnectBody": { "type": "object", "properties": { "return_to": { "type": "string", "format": "uri" }, "shop": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Shopify only, and required there: the store, as `mi-tienda`, `mi-tienda.myshopify.com` or its admin URL (`https://admin.shopify.com/store/mi-tienda`). A custom storefront domain is refused (400, `details.reason: \"invalid_shop\"`): Shopify installs on the myshopify address. Ignored for every other provider." } }, "required": [ "return_to" ] }, "ProviderReturnBody": { "type": "object", "properties": { "handoff_id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "minLength": 1, "maxLength": 200 }, "status": { "type": "string", "enum": [ "success", "pending_selection", "failed", "cancelled" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "ProviderFinalizeBody": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "An `attempt.candidates[].external_id`, verbatim." }, "handoff_id": { "type": "string", "format": "uuid", "description": "The `attempt.handoff.id` of the picker being answered. When sent and it is not the consent this card is waiting on, the answer is 409 `handoff_mismatch` — a stale tab cannot finalize a newer consent’s choice. Omitted: the current picker is finalized." } }, "required": [ "external_id" ] }, "ProviderSyncResult": { "type": "object", "properties": { "enqueued": { "type": "boolean", "enum": [ true ] } }, "required": [ "enqueued" ] }, "ProviderSyncBody": { "type": "object", "properties": { "force": { "type": "boolean", "description": "Switch off products the store no longer lists even when it looks like a mass drop (the drop guard). Only for a merchant who really emptied the store." } } }, "CrmStage": { "type": "object", "properties": { "external_id": { "type": "string", "description": "The CRM’s own stage id — the `{stageId}` a write names." }, "name": { "type": "string", "description": "The stage’s name in the CRM, verbatim." }, "position": { "type": "number", "description": "Its position in the pipeline (CRM order)." }, "outcome": { "type": [ "string", "null" ], "description": "The outcome in force (an `outcomes[].key`; `ignored` = «No contar»), or `null` when the stage counts as nothing yet." }, "outcome_label": { "type": [ "string", "null" ] }, "mark": { "type": "string", "enum": [ "suggested", "changed", "default", "unset" ], "description": "`suggested` — on the suggestion (applied automatically, or chosen to match it); `changed` — someone chose something else; `default` — a value nobody chose (an older default), worth a look; `unset` — not assigned, counts as nothing." }, "suggested": { "type": [ "object", "null" ], "properties": { "outcome": { "type": "string", "description": "An `outcomes[].key`." }, "label": { "type": "string", "description": "Its ready Spanish name («Cita agendada»)." } }, "required": [ "outcome", "label" ], "description": "What the stage’s name points to. Deterministic: the same name always gets the same suggestion. `null` when the name points to nothing — `no_suggestion_label` says so." }, "no_suggestion_label": { "type": [ "string", "null" ] }, "needs_choice": { "type": "boolean", "description": "No suggestion and nobody decided: a person has to pick (the sheet’s banner counts these). The auto-apply never guesses for them." }, "writable": { "type": "boolean" }, "not_writable_label": { "type": [ "string", "null" ], "description": "Why it cannot be edited now, as a sentence." } }, "required": [ "external_id", "name", "position", "outcome", "outcome_label", "mark", "suggested", "no_suggestion_label", "needs_choice", "writable", "not_writable_label" ] }, "CrmStageMapping": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "gohighlevel" ] }, "status": { "type": "string", "enum": [ "ready", "awaiting_sync", "reconnect_required", "not_connected" ], "description": "`ready` — every stage is listed. `awaiting_sync` — connected, the pipelines are still being read. `reconnect_required` — the stages stay listed and editable, but the connection needs re-authorizing. `not_connected` — nothing to list." }, "status_label": { "type": [ "string", "null" ], "description": "A ready sentence for any status but `ready`." }, "synced_at": { "type": [ "string", "null" ], "description": "When the pipelines were last read from the CRM." }, "syncing": { "type": "boolean", "description": "A pipelines read was asked for in the last few minutes." }, "can_write": { "type": "boolean" }, "write_blocked": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "enum": [ "addon_inactive", "access_pending", "measurement_inactive" ] }, "label": { "type": "string" } }, "required": [ "code", "label" ], "description": "Why the mapping cannot be edited now: `addon_inactive` (the Vitrina Ads add-on is off), `access_pending` (edit access is still being enabled — try again in a few minutes), `measurement_inactive` (outcome measurement is not enabled on the workspace)." }, "next_step": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "sync", "reconnect", "connect", "none" ], "description": "`sync` — `POST …/stages/sync`; `reconnect` / `connect` — the connection card’s own `…/connect`; `none`." }, "label": { "type": [ "string", "null" ] } }, "required": [ "action", "label" ] }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" } }, "required": [ "key", "label" ] }, "description": "Every outcome a stage can map to, in picker order, ending in `ignored` («No contar»)." }, "pipelines": { "type": "array", "items": { "type": "object", "properties": { "external_id": { "type": "string", "description": "The CRM’s own pipeline id." }, "name": { "type": "string" }, "account_name": { "type": [ "string", "null" ], "description": "The CRM sub-account — only when several are connected." }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/CrmStage" } } }, "required": [ "external_id", "name", "account_name", "stages" ] }, "description": "Pipelines in CRM order, each with its stages in CRM order." }, "summary": { "type": "object", "properties": { "pipelines": { "type": "number" }, "stages": { "type": "number" }, "suggested": { "type": "number" }, "changed": { "type": "number" }, "needs_choice": { "type": "number" }, "awaiting_sync": { "type": "number" } }, "required": [ "pipelines", "stages", "suggested", "changed", "needs_choice", "awaiting_sync" ] } }, "required": [ "provider", "status", "status_label", "synced_at", "syncing", "can_write", "write_blocked", "next_step", "outcomes", "pipelines", "summary" ] }, "CrmStageOutcomeBody": { "type": "object", "properties": { "outcome": { "type": "string", "minLength": 1, "maxLength": 64, "description": "An `outcomes[].key` from the stages read — `ignored` for «No contar». Anything else is 422 `invalid_outcome`." } }, "required": [ "outcome" ] }, "AdsCoverage": { "type": "object", "properties": { "measured_from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The workspace’s measurement start (America/Santiago day): the earliest ad touch Vitrina holds (an imported historical touch or a conversation an ad opened) or the first day the attribution engine credited an outcome to an ad. `null` = unknown (nothing clipped)." }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The day the response’s figures are counted from: the later of the requested `from` and `measured_from`." }, "clipped": { "type": "boolean", "description": "`true` when measurement started inside the requested period: say «Medimos desde {measured_from}» next to the figures." }, "previous_measured": { "type": "boolean", "description": "`false` when the comparison period was not measured from its first day: show «—» for every comparison, never a delta against it." }, "touches_from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The earliest ad touch Vitrina holds (an imported history, a conversation an ad opened). Bounds the people views («antes de medir»), never a ratio." }, "conversations": { "type": "object", "properties": { "measured_from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clipped": { "type": "boolean" }, "previous_measured": { "type": "boolean" }, "ad_origin_gap": { "type": [ "object", "null" ], "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "from", "to" ], "description": "Days inside the period no ad-origin record covers (between an imported history’s last ad touch and Vitrina’s first ad-opened conversation): their conversations are not attributable to an ad. Name them next to the figures; never estimate them. `null` = none." }, "stages_from": { "type": "object", "properties": { "appointments": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "closes": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "appointments", "closes" ], "description": "The day each STAGE figure of the conversation funnel starts when it is later than the conversations’ own start (an imported history reaches back before Vitrina recorded citas and accepted presupuestos). Non-null = say «citas desde el {day}» / «presupuestos aceptados desde el {day}» next to that figure; `null` = it covers the whole conversation window." } }, "required": [ "measured_from", "from", "clipped", "previous_measured" ], "description": "CONVERSATION-family coverage: conversations and cost per conversation count from the first ad-opened conversation or lead (`measured_from`) — or, when the workspace imported a conversation history with its ad touches, from the start of that history’s complete stretch (as `people`), never from the money start above. Say «Medimos desde» with this date next to those figures, and show «—» for their comparisons when `previous_measured` is false." }, "people": { "type": "object", "properties": { "measured_from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "clipped": { "type": "boolean" }, "previous_measured": { "type": "boolean" }, "ad_origin_gap": { "type": [ "object", "null" ], "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "from", "to" ], "description": "Days inside the period no ad-origin record covers — between the end of an imported history and Vitrina’s first ad-opened conversation. Name them next to the people («sin origen de anuncio el 19 sep»); never estimate them. `null` = none." } }, "required": [ "measured_from", "from", "clipped", "previous_measured", "ad_origin_gap" ], "description": "PEOPLE-family coverage: «personas que escribieron» and «desde anuncios» count from the start of the workspace’s COMPLETE history (`measured_from`): an imported history on its real message times once its census shows it complete, else the conversation start. When `clipped`, the people are a different window from the money: give them their own line naming it, never beside the period’s money. Absent = use `conversations`." }, "payments_connected": { "type": "boolean", "description": "Whether payments reach Vitrina at all (a clinic-software mirror, the money module, or any payment recorded). `false` = every payment-based return (total return, first payment, «$ pagados») is a MISSING measurement: show «—» and say what is needed (connect the clinic’s payments), never «0×» or «$0»." }, "ad_payments_recorded": { "type": "boolean", "description": "Whether anybody an ad brought has EVER paid (a payment counted toward ad return, any day). Present only when the payments rail is Vitrina’s own ledger or a Reservo sales mirror (never a Dentalink / Medilink mirror). `false` with `payments_connected: true` = payments reach Vitrina but no person from an ad has paid yet: an empty state that says so («Aún ningún paciente de anuncios ha pagado»), never «$0 pagados» or «0×». Absent = as before." }, "accepted_recorded": { "type": "boolean", "description": "Whether the workspace has ever recorded an accepted quote / closed sale. `false` = the accepted-quotes return is a MISSING measurement: «—», never «0×» or «$0»." }, "start_unknown": { "type": "boolean", "description": "`true` when the measurement start could not be read: every ratio (return, primer pago, MER, accepted plans) is unknown — show «—», never a return over days nobody measured." } }, "required": [ "measured_from", "from", "clipped", "previous_measured" ], "description": "The coverage window (see `AdsCoverage`); absent on the sample." }, "AdsPatientReturn": { "type": [ "object", "null" ], "properties": { "patients": { "type": "integer", "minimum": 0, "description": "Ad people with at least one counted payment in the period." }, "payments": { "type": "integer", "minimum": 0 }, "value": { "type": "number", "minimum": 0, "description": "Their payments in the period (CLP): first + later." }, "first_value": { "type": "number", "minimum": 0, "description": "Of `value`, each person’s first payment." }, "later_value": { "type": "number", "minimum": 0, "description": "Of `value`, the later payments (cuotas, more treatment)." }, "arrived_value": { "type": "number", "minimum": 0, "description": "Of `value`, the payments of people whose FIRST message came from an ad («llegaron por un anuncio»). `arrived_value + returned_value = value`. Absent on the sample." }, "returned_value": { "type": "number", "minimum": 0, "description": "Of `value`, the payments counted through a LATER conversation an ad opened (re-engagement, retargeting — «volvieron por un anuncio»). Absent on the sample." }, "arrived_patients": { "type": "integer", "minimum": 0, "description": "Of `patients`, the people counted as «llegaron»; `arrived_patients + returned_patients = patients`." }, "returned_patients": { "type": "integer", "minimum": 0, "description": "Of `patients`, the people counted as «volvieron»." }, "roas": { "type": [ "number", "null" ], "description": "`value ÷ spend`; `null` when spend is unknown or 0." } }, "required": [ "patients", "payments", "value", "first_value", "later_value", "roas" ], "description": "«Retorno»: the payments of the period counted toward ad return whose counting ad (the ad-opened conversation within the 12 months before the payment) is this ad or one of this campaign’s ads. Not set on ad sets. `null` = unknown." }, "AdsReportRow": { "type": "object", "properties": { "spend": { "type": [ "number", "null" ] }, "funnel": { "type": "object", "properties": { "conversations": { "type": [ "integer", "null" ], "minimum": 0 }, "replied": { "type": [ "integer", "null" ], "minimum": 0 }, "appointments": { "type": [ "integer", "null" ], "minimum": 0 }, "attended": { "type": [ "integer", "null" ], "minimum": 0 }, "closes": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "conversations", "replied", "appointments", "attended", "closes" ], "description": "Vitrina’s own funnel: conversations each ad OPENED in the period and the stages recorded against them (a campaign / ad set sums its ads). `null` = unknown (the read failed), never 0." }, "cost_per": { "type": "object", "properties": { "conversation": { "type": [ "number", "null" ] }, "appointment": { "type": [ "number", "null" ] }, "attended": { "type": [ "number", "null" ] }, "close": { "type": [ "number", "null" ] } }, "required": [ "conversation", "appointment", "attended", "close" ] }, "cash": { "type": [ "number", "null" ], "description": "Payments credited to the entity (CLP). Cash only." }, "return": { "type": [ "number", "null" ], "description": "cash ÷ spend. `null` when no payment was recorded in the period (see `cash_recorded`) — the return is unknown then, never 0×." }, "accepted_value": { "type": [ "number", "null" ], "description": "The recorded value of the accepted presupuestos / closed sales of the conversations the entity opened (CLP) — pipeline, never cash. `null` = unknown." }, "accepted_count": { "type": [ "integer", "null" ], "description": "How many accepted presupuestos / closed sales `accepted_value` is. Totals and campaign rows: the engine-credited list Resumen sums." }, "diagnosed": { "type": [ "integer", "null" ], "description": "D60 · «Con diagnóstico»: people whose conversation the entity opened and who got a presupuesto presented. Absent = unknown." }, "accepted_return": { "type": [ "number", "null" ], "description": "`accepted_value` ÷ spend («Retorno en presupuestos»). `null` = unknown or no spend." }, "patient_return": { "$ref": "#/components/schemas/AdsPatientReturn" }, "meta": { "type": "object", "properties": { "conversations_started": { "type": [ "number", "null" ] }, "cost_per_conversation": { "type": [ "number", "null" ] } }, "required": [ "conversations_started", "cost_per_conversation" ], "description": "Meta’s OWN figures (its 7-day window, every sender) — never added to Vitrina’s." }, "external_id": { "type": [ "string", "null" ], "description": "Platform id; `null` for the unmapped bucket." }, "level": { "type": "string", "enum": [ "campaign", "ad_set", "ad" ] }, "name": { "type": "string" }, "parent": { "type": [ "object", "null" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "external_id", "name" ], "description": "An ad’s ad set / an ad set’s campaign; `null` for a campaign." }, "thumbnail_url": { "type": [ "string", "null" ] }, "spark": { "type": [ "array", "null" ], "items": { "type": "number" }, "description": "Daily spend, oldest first; `null` unread." }, "unmapped": { "type": "boolean", "enum": [ true ], "description": "Ads that opened conversations but have no row at this level yet." } }, "required": [ "spend", "funnel", "cost_per", "cash", "return", "meta", "external_id", "level", "name", "parent", "thumbnail_url", "spark" ] }, "AdsReport": { "type": "object", "properties": { "level": { "type": "string", "enum": [ "campaign", "ad_set", "ad" ] }, "window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "description": "The days the rows were read over: `from` is the later of the requested `from` and the measurement start (`coverage`)." }, "coverage": { "$ref": "#/components/schemas/AdsCoverage" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/AdsReportRow" } }, "tail": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "website", "portals", "direct" ] }, "conversations": { "type": "integer", "minimum": 0 } }, "required": [ "key", "conversations" ] }, "description": "«Sin anuncio»: the period’s conversations with no ad behind them. `null` = unknown." }, "totals": { "type": "object", "properties": { "spend": { "type": [ "number", "null" ] }, "funnel": { "type": "object", "properties": { "conversations": { "type": [ "integer", "null" ], "minimum": 0 }, "replied": { "type": [ "integer", "null" ], "minimum": 0 }, "appointments": { "type": [ "integer", "null" ], "minimum": 0 }, "attended": { "type": [ "integer", "null" ], "minimum": 0 }, "closes": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "conversations", "replied", "appointments", "attended", "closes" ], "description": "Vitrina’s own funnel: conversations each ad OPENED in the period and the stages recorded against them (a campaign / ad set sums its ads). `null` = unknown (the read failed), never 0." }, "cost_per": { "type": "object", "properties": { "conversation": { "type": [ "number", "null" ] }, "appointment": { "type": [ "number", "null" ] }, "attended": { "type": [ "number", "null" ] }, "close": { "type": [ "number", "null" ] } }, "required": [ "conversation", "appointment", "attended", "close" ] }, "cash": { "type": [ "number", "null" ], "description": "Payments credited to the entity (CLP). Cash only." }, "return": { "type": [ "number", "null" ], "description": "cash ÷ spend. `null` when no payment was recorded in the period (see `cash_recorded`) — the return is unknown then, never 0×." }, "accepted_value": { "type": [ "number", "null" ], "description": "The recorded value of the accepted presupuestos / closed sales of the conversations the entity opened (CLP) — pipeline, never cash. `null` = unknown." }, "accepted_count": { "type": [ "integer", "null" ], "description": "How many accepted presupuestos / closed sales `accepted_value` is. Totals and campaign rows: the engine-credited list Resumen sums." }, "diagnosed": { "type": [ "integer", "null" ], "description": "D60 · «Con diagnóstico»: people whose conversation the entity opened and who got a presupuesto presented. Absent = unknown." }, "accepted_return": { "type": [ "number", "null" ], "description": "`accepted_value` ÷ spend («Retorno en presupuestos»). `null` = unknown or no spend." }, "patient_return": { "$ref": "#/components/schemas/AdsPatientReturn" }, "meta": { "type": "object", "properties": { "conversations_started": { "type": [ "number", "null" ] }, "cost_per_conversation": { "type": [ "number", "null" ] } }, "required": [ "conversations_started", "cost_per_conversation" ], "description": "Meta’s OWN figures (its 7-day window, every sender) — never added to Vitrina’s." } }, "required": [ "spend", "funnel", "cost_per", "cash", "return", "meta" ] }, "pipeline": { "type": [ "object", "null" ], "properties": { "closed_count": { "type": "integer" }, "closed_value": { "type": "number" } }, "required": [ "closed_count", "closed_value" ], "description": "Closes credited to an ad and their recorded value — PIPELINE, never in `return`." }, "cash_recorded": { "type": "boolean" }, "reconciliation": { "type": "object", "properties": { "overview_spend": { "type": [ "number", "null" ] }, "spend_matches": { "type": [ "boolean", "null" ] }, "conversations_total": { "type": [ "integer", "null" ], "minimum": 0 }, "conversations_from_ads": { "type": [ "integer", "null" ], "minimum": 0 }, "conversations_without_ad": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "overview_spend", "spend_matches", "conversations_total", "conversations_from_ads", "conversations_without_ad" ] } }, "required": [ "level", "window", "rows", "tail", "totals", "pipeline", "cash_recorded", "reconciliation" ] }, "AdsAdSheet": { "type": "object", "properties": { "ad": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" }, "name": { "type": "string" }, "ad_set": { "type": [ "object", "null" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "external_id", "name" ] }, "campaign": { "type": [ "object", "null" ], "properties": { "external_id": { "type": "string" } }, "required": [ "external_id" ] }, "thumbnail_url": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "has_video": { "type": "boolean" }, "video_external_id": { "type": [ "string", "null" ], "description": "Meta’s id of the ad’s video; `null` for an image ad. Play it with `GET /ads/ads/{id}/video` (the source is short-lived: ask on play)." }, "ads_manager_url": { "type": [ "string", "null" ], "description": "The ad in Meta Ads Manager (opens in a new tab); `null` when the ad account is unknown." }, "spend": { "type": [ "number", "null" ] }, "impressions": { "type": "number" }, "clicks": { "type": "number" }, "ctr": { "type": "number" }, "cpm": { "type": "number" }, "cpc": { "type": "number" }, "cash_count": { "type": "number" }, "cash_value": { "type": "number" }, "meta_conversations_started": { "type": [ "number", "null" ] } }, "required": [ "external_id", "name", "ad_set", "campaign", "thumbnail_url", "title", "body", "has_video", "video_external_id", "ads_manager_url", "spend", "impressions", "clicks", "ctr", "cpm", "cpc", "cash_count", "cash_value", "meta_conversations_started" ], "description": "The creative and the delivery metrics; `null` when the engine read failed." }, "window": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ] }, "row": { "type": "object", "properties": { "spend": { "type": [ "number", "null" ] }, "funnel": { "type": "object", "properties": { "conversations": { "type": [ "integer", "null" ], "minimum": 0 }, "replied": { "type": [ "integer", "null" ], "minimum": 0 }, "appointments": { "type": [ "integer", "null" ], "minimum": 0 }, "attended": { "type": [ "integer", "null" ], "minimum": 0 }, "closes": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "conversations", "replied", "appointments", "attended", "closes" ], "description": "Vitrina’s own funnel: conversations each ad OPENED in the period and the stages recorded against them (a campaign / ad set sums its ads). `null` = unknown (the read failed), never 0." }, "cost_per": { "type": "object", "properties": { "conversation": { "type": [ "number", "null" ] }, "appointment": { "type": [ "number", "null" ] }, "attended": { "type": [ "number", "null" ] }, "close": { "type": [ "number", "null" ] } }, "required": [ "conversation", "appointment", "attended", "close" ] }, "cash": { "type": [ "number", "null" ], "description": "Payments credited to the entity (CLP). Cash only." }, "return": { "type": [ "number", "null" ], "description": "cash ÷ spend. `null` when no payment was recorded in the period (see `cash_recorded`) — the return is unknown then, never 0×." }, "accepted_value": { "type": [ "number", "null" ], "description": "The recorded value of the accepted presupuestos / closed sales of the conversations the entity opened (CLP) — pipeline, never cash. `null` = unknown." }, "accepted_count": { "type": [ "integer", "null" ], "description": "How many accepted presupuestos / closed sales `accepted_value` is. Totals and campaign rows: the engine-credited list Resumen sums." }, "diagnosed": { "type": [ "integer", "null" ], "description": "D60 · «Con diagnóstico»: people whose conversation the entity opened and who got a presupuesto presented. Absent = unknown." }, "accepted_return": { "type": [ "number", "null" ], "description": "`accepted_value` ÷ spend («Retorno en presupuestos»). `null` = unknown or no spend." }, "patient_return": { "$ref": "#/components/schemas/AdsPatientReturn" }, "meta": { "type": "object", "properties": { "conversations_started": { "type": [ "number", "null" ] }, "cost_per_conversation": { "type": [ "number", "null" ] } }, "required": [ "conversations_started", "cost_per_conversation" ], "description": "Meta’s OWN figures (its 7-day window, every sender) — never added to Vitrina’s." } }, "required": [ "spend", "funnel", "cost_per", "cash", "return", "meta" ], "description": "The same figures as the Reporte row for this ad." }, "cash_recorded": { "type": "boolean" }, "people": { "type": "array", "items": { "type": "object", "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "label": { "type": "string", "description": "Initials, or the name where allowed. Never a phone or an e-mail." }, "masked": { "type": "boolean" }, "stage": { "type": [ "string", "null" ] }, "stage_at": { "type": [ "string", "null" ] }, "opened_at": { "type": "string" }, "value": { "type": [ "number", "null" ] } }, "required": [ "conversation_id", "contact_id", "label", "masked", "stage", "stage_at", "opened_at", "value" ] }, "description": "The conversations this ad opened, newest first. Healthcare: always initials. Elsewhere a name only with `contacts:read`. No export." }, "people_more": { "type": "boolean" }, "people_hidden": { "type": "boolean", "description": "The caller lacks `contacts:read`: `people` is empty on purpose." } }, "required": [ "ad", "window", "row", "cash_recorded", "people", "people_more", "people_hidden" ] }, "AdsAdVideo": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "source", "embed" ], "description": "`source`: a direct URL a `