Servicialo

La capa de orquestación para la economía de servicios en la era de agentes AI

Un protocolo abierto para coordinación de agenda, identidad, verificación<br> de entrega y liquidación financiera de servicios profesionales.

Protocolo abierto Legible por máquinas Agent-native Apache-2.0

Sitio web ・ Especificación ・ Gobernanza ・ MCP Server ・ npm

Nuevo en Servicialo? Empieza aqui → SPEC.md

Spec completa (crawler-friendly): https://servicialo.com/spec

Read in English

Protocol Specification

For a formal description of the architecture, message flows, and data model:

• Whitepaper v0.9 — formal protocol specification
• Protocol repository — schemas, RFCs, and reference materials
• PROTOCOL.md — full specification in this repo

¿Por dónde empiezo?

Tengo un negocio de servicios y quiero que agentes AI descubran y agenden mis servicios → Necesitas una plataforma compatible con el protocolo, no este repositorio. Coordinalo es la implementación de referencia. A medida que el protocolo madure, esperamos que surjan muchas más plataformas compatibles.

Soy un desarrollador que quiere construir una plataforma compatible con el protocolo → Sigue leyendo. Empieza por IMPLEMENTING.md.

El problema

Sin un protocolo estándar, cada plataforma de servicios habla su propio idioma. Un agente AI que quiere agendar una cita médica, verificar una reparación a domicilio o cobrar una consulta legal necesita una integración distinta para cada una. Los datos quedan en silos, la interoperabilidad requiere integraciones custom, y la inteligencia colectiva sobre entrega de servicios nunca se forma.

Servicialo es el protocolo común. Define el esquema mínimo viable para que cualquier agente AI coordine cualquier servicio profesional en cualquier plataforma compatible — sin integración adicional.

Primitivas del protocolo

Servicialo define cuatro primitivas de coordinación. Juntas cubren la cadena de valor completa de la entrega de servicios profesionales:

Cada primitiva se especifica de forma independiente. Las implementaciones adoptan lo que necesitan.

Qué es un servicio

Un servicio es una promesa de transformación entregada en un momento y lugar específico.

A diferencia de un producto, un servicio no se puede almacenar, revender ni devolver. Se consume en el momento en que se entrega. Eso lo hace fundamentalmente diferente — y es por eso que necesita su propio protocolo.

Un servicio nace de tres fuentes:

Las 8 dimensiones

Todo servicio profesional — desde una sesión de kinesiología hasta una auditoría tributaria — se modela con las mismas 8 dimensiones:

El pagador no siempre es el cliente. En salud paga la aseguradora. En corporativo paga la empresa. En educación paga el apoderado. El protocolo separa explícitamente al cliente del pagador — porque en la vida real casi nunca son la misma persona.

Los 9 estados universales

No importa si es un masaje o una auditoría. Todo servicio transiciona por el mismo ciclo de vida:

Solicitado → Agendado → Confirmado → En Curso → Completado → Documentado → Facturado → Cobrado → Verificado

Verificado es el cierre. El cliente no puede verificar hasta tener el cuadro completo: la evidencia documentada, la factura emitida y el cobro aplicado. Verificación prematura obliga al cliente a confirmar algo que aún no tiene registro formal.

Las excepciones son la regla

Las excepciones no son casos excepcionales. Ocurren en el 15–30% de las citas. Un servicio bien diseñado define qué pasa cuando las cosas no salen según el plan:

Servicio y Orden de Servicio

El protocolo se construye sobre dos objetos y su relación:

Organización
└── Orden de Servicio            ← acuerdo comercial (opcional)
    ├── alcance                   qué servicios, cuántos, de qué tipo
    ├── precio                    cómo se calcula el valor
    ├── esquema de pagos          cuándo se mueve el dinero
    └── Servicios                 ← unidades atómicas de entrega
        └── 8 dimensiones cada uno

El Servicio es la unidad atómica de entrega — lo que realmente ocurrió. La Orden de Servicio es el acuerdo comercial que agrupa servicios bajo un alcance, un precio y un esquema de pagos.

Cuando un Servicio pertenece a una Orden, su dimensión de cobro es informativa — registra el valor económico, pero no genera factura. La facturación es responsabilidad exclusiva de la Orden.

La misma estructura funciona para cualquier vertical:

Evidencia por vertical

Cada vertical define qué constituye prueba de que el servicio ocurrió. Sin ambigüedad — para que un algoritmo pueda resolver el 80% de las disputas sin intervención humana:

Regla de resolución: Si registros de entrada/salida existen y ficha clínica está firmada por ambas partes → servicio entregado. Si falta ficha o firma → escalar.

Regla de resolución: Si fotos antes/después existen con metadatos válidos y lista completa → servicio entregado. Si falta firma del cliente → escalar.

Regla de resolución: Si minuta existe y horas registradas dentro del rango acordado → servicio entregado. Si horas exceden lo acordado sin justificación → escalar.

Regla de resolución: Si asistencia registrada y material entregado → servicio entregado. Si falta evaluación y contrato la requiere → escalar.

Resolución de disputas

Cuando hay desacuerdo, el mecanismo no depende de buena voluntad, no requiere un juez centralizado, y un agente AI puede ejecutarlo con la misma confianza que un humano:

1. Apertura — Cualquier parte abre disputa dentro del plazo definido. Se congela el cobro automáticamente.

2. Revisión de evidencia — Se solicita evidencia adicional de ambas partes. El sistema compara evidencia registrada contra el contrato.

3. Resolución — Si proveedor gana: Cobrado → Verificado. Si cliente gana: Cancelado con balance restaurado.

80/20. El 80% de las disputas se resuelven automáticamente comparando evidencia contra contrato. Sin intervención humana, sin discrecionalidad, sin demora. El 20% restante escala a árbitros del mismo vertical profesional que votan en 48 horas.

Servidor MCP

Servicialo expone sus herramientas como un servidor MCP, permitiendo que agentes AI descubran y coordinen servicios profesionales de forma nativa.

Inicio rápido

El package @servicialo/mcp-server es un thin-client que conecta a la API HTTP de una plataforma Servicialo-compatible. Por defecto apunta a Coordinalo (servicialo.com). Si estás construyendo tu propio backend, apunta al tuyo con SERVICIALO_BASE_URL. Si eres una organización usuaria (clínica, consultora, etc.), las credenciales las obtienes desde tu plataforma — no necesitas instalar este package directamente.

npx -y @servicialo/mcp-server

Con eso, tu agente ya puede buscar organizaciones, consultar disponibilidad y listar servicios — sin credenciales.

Modo autenticado

Para el ciclo completo — agendar, verificar entrega, cobrar:

{
  "mcpServers": {
    "servicialo": {
      "command": "npx",
      "args": ["-y", "@servicialo/mcp-server"],
      "env": {
        "SERVICIALO_API_KEY": "tu_api_key",
        "SERVICIALO_ORG_ID": "tu_org_id"
      }
    }
  }
}

Las credenciales las obtiene cada organización desde la plataforma Servicialo-compatible que utilice.

Las fases del agente — 34 herramientas

Un agente bien diseñado sigue este orden:

El servidor envía telemetría anónima al arrancar para estadísticas del protocolo. Se puede desactivar con SERVICIALO_TELEMETRY=false.

El protocolo garantiza que cualquier agente pueda completar el ciclo completo con cualquier implementación compatible.

Ejemplos completos

Sesión de kinesiología — Vertical salud. Registro de entrada con GPS, ficha clínica firmada, pago por transferencia.

Reparación eléctrica — Vertical hogar. Visita a domicilio, fotos antes/después, lista de verificación, firma del cliente, pago en efectivo.

A2A Ready

Servicialo soporta A2A (Agent-to-Agent) como extensión opcional, permitiendo que agentes externos (Salesforce Agentforce, Google ADK, etc.) descubran y reserven servicios sin pasar por MCP.

Guía completa: docs/a2a-interoperability.md

Los 7 principios

Arquitectura por capas

Adopta solo lo que necesitas. Core cubre el ciclo completo de entrega. Las extensiones agregan capacidades para operaciones especializadas.

Servicialo Core — estable

Todo lo necesario para modelar un servicio profesional de principio a fin.

Para cualquier plataforma donde dos partes toman un compromiso de entrega y necesitan una cuenta verificable de lo que ocurrió — desde una sociedad de psicólogos hasta una empresa de limpieza con múltiples cuentas, equipos y personal.

Incluye: 8 dimensiones · 9 estados del ciclo de vida · 6 flujos de excepción · 7 principios fundamentales · gestión de recursos · órdenes de servicio · prueba de entrega · protocolo MCP (34 herramientas) · resolución DNS · interoperabilidad A2A

Servicialo/Finanzas — en diseño

Distribución de pagos entre profesional, organización e infraestructura — con reglas claras de liquidación.

Para plataformas que intermedian pagos entre clientes y profesionales, o que cobran comisiones.

Servicialo/Disputas — en diseño

Resolución formal con arbitraje algorítmico (~80%) y por pares del mismo vertical (~20%).

Para plataformas con volumen suficiente o donde el monto por servicio hace que las disputas sean económicamente relevantes.

Schema

JSON Schemas para validación automática: schema/service.schema.json y schema/service-order.schema.json

# ─────────────────────────────────────────────
# SERVICIALO v0.9
# Dos entidades: Orden + Servicios atómicos
# ─────────────────────────────────────────────

orden_de_servicio:
  id: texto                      # Identificador único
  alcance: texto                 # Qué se acuerda entregar
  precio: número                 # Precio total acordado
  esquema_pagos: texto           # prepago | por_sesión | mensual
  currency: texto                # ISO 4217

  servicios[]:                   # Cada servicio atómico — 8 dimensiones

    servicio:
      id: texto
      orden_de_servicio_id: texto  # Referencia a la Orden padre
      tipo: texto                # Categoría del servicio
      vertical: texto            # salud | legal | hogar | educación | ...
      nombre: texto              # Nombre legible
      duración_minutos: entero
      visibilidad: texto         # public | unlisted | private

      proveedor:
        id: texto
        credenciales: texto[]    # Certificaciones requeridas
        puntaje_confianza: número  # 0-100 calculado por historial
        organización_id: texto

      cliente:
        id: texto
        pagador_id: texto        # Puede diferir del cliente

      agenda:
        solicitado_en: fecha_hora
        agendado_para: fecha_hora
        duración_esperada: minutos

      ubicación:
        tipo: presencial | virtual | domicilio
        dirección: texto
        recurso_id: texto        # Opcional — referencia a recurso físico

      ciclo_de_vida:
        estado_actual: enum[9]   # Los 9 estados universales
        transiciones: transición[]
        excepciones: excepción[]

      prueba_de_entrega:
        entrada: fecha_hora
        salida: fecha_hora
        duración_real: minutos
        evidencia: evidencia[]   # GPS, firma, fotos, documentos

      cobro:
        orden_de_servicio_id: texto  # Referencia a la Orden padre
        monto:
          valor: número
          moneda: texto          # ISO 4217
        pagador: referencia
        estado: pendiente | cobrado | facturado | pagado | disputado
        cobrado_en: fecha_hora
        documento_tributario: referencia  # Boleta/factura si se emitió

      mandato:                   # Delegación explícita a agente IA
        mandato_id: texto        # UUID único
        principal_id: texto      # Humano u organización
        agente_id: texto         # Agente que recibe la delegación
        alcances: texto[]        # resource:action (e.g. schedule:write)
        estado: activo | expirado | revocado | suspendido

# Ledger computado desde servicios verificados — nunca editable

Implementaciones

Cualquier plataforma puede implementar Servicialo. Para ser listada debe modelar las 8 dimensiones, implementar los 9 estados, manejar al menos 3 de los 6 flujos de excepción, adherir a los 7 principios fundamentales y exponer una API conectable al MCP server.

Coordinalo es la implementación de referencia. El segundo nodo es una oportunidad abierta — ver IMPLEMENTORS.md.

Para implementadores

Guía paso a paso para construir una plataforma compatible desde cero — 7 pasos, el primero toma 20 minutos. Empezar aquí: IMPLEMENTING.md (English)

Referencias adicionales:

• schema/evidence/ — Schemas de evidencia por vertical (salud, hogar, legal, educación, consultoría)
• ERRORS.md — Códigos de error del protocolo
• WEBHOOKS.md — Notificaciones asíncronas de cambios de estado (borrador)

Qué hay en este repositorio

servicialo/
├── app/                  # servicialo.com — sitio del protocolo (Next.js)
├── components/           # Componentes del sitio
├── examples/             # Conversaciones agente-servidor
├── lib/                  # Datos del protocolo
├── packages/
│   └── mcp-server/       # @servicialo/mcp-server — servidor MCP (npm)
├── schema/               # JSON Schemas para validación
│   ├── evidence/         # Schemas de evidencia por vertical
│   │   ├── base.schema.json       # Envelope compartido
│   │   ├── health.schema.json     # Salud
│   │   ├── home.schema.json       # Hogar
│   │   ├── legal.schema.json      # Legal
│   │   ├── education.schema.json  # Educación
│   │   └── consulting.schema.json # Consultoría
│   ├── service.schema.json
│   ├── service-order.schema.json
│   └── ...
├── SPEC.md               # Quick spec — referencia autocontenida para evaluadores
├── PROTOCOL.md           # Especificación completa
├── ERRORS.md             # Códigos de error del protocolo
├── WEBHOOKS.md           # Especificación de webhooks (borrador)
├── IMPLEMENTORS.md       # Guía para construir una implementación
├── GOVERNANCE.md         # Gobernanza de red y política de datos
└── README.md

Ecosystem

• Network explorer — live nodes implementing the protocol
• awesome-servicialo — curated list of integrations, clients, and tools
• Using Servicialo? Add your implementation

Licencia

Apache-2.0 — Servicialo es un protocolo abierto. Cualquiera puede implementarlo.