PortalFirma

MCP · Tools

Catálogo de tools

Tools registradas en api-mcp. Requieren sesión OAuth (Bearer pf_mcp_at_*). Cada tool incluye pregunta del usuario, arguments de entrada y respuesta MCP.

Los ejemplos están pensados para agentes (Claude, Cursor, N8N). El usuario habla en lenguaje natural; el agente elige la tool, arma los arguments y muestra la respuesta. Todas las acciones quedan acotadas a la entidad del token OAuth.

Session

get_partner_sessionread

Get partner session

Devuelve entity_id, user_id y person_id de la sesión OAuth.

Pregunta del usuario

“¿Con qué partner estoy autenticado en esta sesión MCP?”
Entrada (arguments)
{}
Respuesta MCP
{
  "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "user_id": "u9f8e7d6-c5b4-3210-9876-543210fedcba",
  "person_id": "p1234567-89ab-cdef-0123-456789abcdef",
  "source": "oauth"
}

Útil al inicio de la conversación para confirmar el contexto. No requiere parámetros.

Document

ingest_document_toolswrite

Ingest document

Ingesta PDF/DOCX en base64 (adjuntos del chat). Devuelve document_id. No acepta URL.

Pregunta del usuario · ejemplo 1

“Te adjunté el mandato.pdf en el chat. Ingéstalo para poder firmarlo después.”
Entrada (arguments)
{
  "source": "base64",
  "base64": "JVBERi0xLjQKJc… (contenido del PDF en base64)",
  "filename": "mandato.pdf"
}
Respuesta MCP
{
  "fileId": "f0a1b2c3-d4e5-6789-abcd-ef0123456789",
  "name": "mandato.pdf"
}

base64 es obligatorio. El agente lee el adjunto, lo codifica y llama la tool. El fileId es el document_id para search_document_content o send_to_sign_document_tools.

Pregunta del usuario · ejemplo 2

“Ingesta este contrato.pdf que te adjunté y guárdalo en la carpeta Documentos MCP.”
Entrada (arguments)
{
  "source": "base64",
  "base64": "data:application/pdf;base64,JVBERi0xLjQKJc…",
  "filename": "contrato.pdf",
  "folder_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
Respuesta MCP
{
  "fileId": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "name": "contrato.pdf"
}

folder_id es opcional. Acepta prefijo data:application/pdf;base64,… Máx ~20MB.

RAG

search_document_contentread

Search document content

Busca contenido en documentos ingeridos (búsqueda semántica).

Pregunta del usuario

“En el documento f0a1b2c3-d4e5-6789-abcd-ef0123456789, ¿qué dice sobre el plazo de vigencia?”
Entrada (arguments)
{
  "document_id": "f0a1b2c3-d4e5-6789-abcd-ef0123456789",
  "query": "plazo de vigencia"
}
Respuesta MCP
{
  "documents": [
    {
      "id": "f0a1b2c3-d4e5-6789-abcd-ef0123456789",
      "documentName": "mandato.pdf",
      "chunk": [
        "El presente mandato tendrá una vigencia de doce (12) meses contados desde la fecha de firma...",
        "Las partes podrán prorrogar el plazo de común acuerdo por escrito."
      ]
    }
  ]
}

Requiere document_id de un archivo ya ingerido que pertenezca a tu entidad.

PDF

extract_signers_document_toolsread

Extract document signers

Extrae firmantes del PDF y aplica tipo de documento (manual o auto-detectado por título).

Pregunta del usuario

“Extrae los firmantes del PDF con document_id f0a1b2c3-d4e5-6789-abcd-ef0123456789”
Entrada (arguments)
{
  "document_id": "f0a1b2c3-d4e5-6789-abcd-ef0123456789"
}
Respuesta MCP
{
  "typeDocument": "Mandato",
  "summary": "Mandato especial entre María González y Juan Soto.",
  "firmantes": [
    {
      "rut": "12.345.678-9",
      "fullName": "María González Pérez",
      "email": "maria.gonzalez@ejemplo.cl",
      "phone": "",
      "alias": "Mandante",
      "typeSign": "avanzada"
    },
    {
      "rut": "9.876.543-2",
      "fullName": "Juan Soto Rivas",
      "email": "",
      "phone": "",
      "alias": "Mandatario",
      "typeSign": "avanzada"
    }
  ],
  "documentConfig": {
    "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
    "title": "Mandato",
    "type_sign": "avanzada",
    "notarial_procedure": "legalization",
    "required_fields": {
      "rut": true,
      "alias": true,
      "name": true,
      "email": true,
      "phone": false,
      "idDocument": false
    }
  },
  "document_config_id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "type_sign": "avanzada",
  "notarial_procedure": "legalization",
  "documentConfigSource": "match",
  "required_fields": {
    "rut": true,
    "alias": true,
    "name": true,
    "email": true,
    "phone": false,
    "idDocument": false
  },
  "missing_fields": [
    {
      "index": 1,
      "alias": "Mandatario",
      "fields": ["email"]
    }
  ],
  "ask_type_sign": false,
  "idDocument_warning": null
}

document_config_id es opcional en la entrada. Si falta, se intenta auto-detectar. Pide al usuario solo missing_fields. No pidas tipo de firma si ask_type_sign es false. Copia document_config_id al enviar a firmar.

Firma

send_to_sign_document_toolswrite

Send document to sign

Envía documento a firma desde el agente (checkout + firmantes).

Pregunta del usuario

“Envía a firmar el documento f0a1b2c3-… con María González y Juan Soto, usando el tipo Mandato. El pagador es pagos@miempresa.cl”
Entrada (arguments)
{
  "document_id": "f0a1b2c3-d4e5-6789-abcd-ef0123456789",
  "document_config_id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890",
  "email": "pagos@miempresa.cl",
  "protocolization": "none" | "legalization" | "protocolization",
  "signatories": [
    {
      "rut": "12.345.678-9",
      "fullName": "María González Pérez",
      "email": "maria.gonzalez@ejemplo.cl",
      "phone": "",
      "alias": "Mandante"
    },
    {
      "rut": "9.876.543-2",
      "fullName": "Juan Soto Rivas",
      "email": "juan.soto@ejemplo.cl",
      "phone": "",
      "alias": "Mandatario"
    }
  ]
}
Respuesta MCP
{
  "contractId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "operation": 482910,
  "registered": [
    {
      "rut": "12.345.678-9",
      "fullName": "María González Pérez",
      "email": "maria.gonzalez@ejemplo.cl",
      "phone": "",
      "alias": "Mandante",
      "typeSign": "avanzada"
    }
  ],
  "count": 2,
  "payment": {
    "url": "https://www.flow.cl/app/web/pay.php?token=…",
    "amount": 15990,
    "method": "flow"
  }
}

Flujo: ingest → extract (match de tipo si hay) → pedir solo missing_fields → send_to_sign con el mismo document_config_id si aplica. Con tipo no envíes typeSign ni protocolization. Sin tipo, protocolization es none, legalization o protocolization. El partner se toma del token; no envíes entity_id.

Operaciones

process_detail_get_by_operationread

Get process detail

Detalle de proceso ligado a una operación (firmantes, IDs, links).

Pregunta del usuario

“Muéstrame el detalle de la operación 482910”
Entrada (arguments)
{
  "operation": 482910
}
Respuesta MCP
{
  "processId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "operation": 482910,
  "status": "starting",
  "signatories": [
    {
      "personId": "p1234567-89ab-cdef-0123-456789abcdef",
      "contractSignatoryId": "cs111111-2222-3333-4444-555555555555",
      "contractEntityPerson_id": "cep11111-2222-3333-4444-555555555555",
      "rut": "12.345.678-9",
      "name": "María",
      "email": "maria.gonzalez@ejemplo.cl",
      "phone": "+56912345678",
      "url": "https://firma.portalfirma.cl/sign/…",
      "signed": false
    }
  ],
  "files": [
    {
      "fileName": "Contrato firmado o en proceso de firma",
      "fileUrl": "https://…/mcp/file?fileId=…"
    }
  ]
}

Fuente principal de IDs para operation_manage_signing_tools. Solo operaciones de tu entidad.

operation_get_operation_by_rutread

Get operations by RUT

Busca operaciones por RUT de firmante en un rango de fechas.

Pregunta del usuario

“¿Qué operaciones tiene el RUT 12.345.678-9 entre el 1 de enero y el 31 de marzo de 2026? Máximo 20.”
Entrada (arguments)
{
  "rut": "12.345.678-9",
  "startDate": "2026-01-01",
  "endDate": "2026-03-31",
  "limit": 20
}
Respuesta MCP
{
  "rut": "12.345.678-9",
  "startDate": "2026-01-01",
  "endDate": "2026-03-31",
  "limit": 20,
  "totalInRange": 3,
  "operations": [
    {
      "contract_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "operation": 482910,
      "contractSignatoryId": "cs111111-2222-3333-4444-555555555555",
      "signed": false,
      "stage": "starting",
      "document_name": "Mandato",
      "createdDateAt": "2026-02-10T15:22:00.000Z",
      "updatedDateAt": "2026-02-11T09:01:00.000Z"
    }
  ]
}

Siempre envía startDate, endDate (máx. 366 días) y limit (1–100). Solo operaciones de tu entidad.

operation_get_operation_by_phoneread

Get operations by phone

Busca operaciones por teléfono de firmante en un rango de fechas.

Pregunta del usuario

“Busca procesos asociados al teléfono +56 9 1234 5678 entre el 1 de febrero y el 28 de febrero de 2026, límite 10.”
Entrada (arguments)
{
  "phone": "+56912345678",
  "startDate": "2026-02-01",
  "endDate": "2026-02-28",
  "limit": 10
}
Respuesta MCP
{
  "phone": "56912345678",
  "startDate": "2026-02-01",
  "endDate": "2026-02-28",
  "limit": 10,
  "totalInRange": 1,
  "operations": [
    {
      "contract_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "operation": 482910,
      "contractSignatoryId": "cs111111-2222-3333-4444-555555555555",
      "signed": false,
      "stage": "starting",
      "document_name": "Mandato",
      "createdDateAt": "2026-02-10T15:22:00.000Z",
      "updatedDateAt": "2026-02-11T09:01:00.000Z"
    }
  ]
}
operation_manage_signing_toolswrite

Manage signing operation

Gestiona el flujo de firma: envío, reenvío, datos, tipo de firma, links, turno y eliminación.

Pregunta del usuario · ejemplo 1

“Reenvía el link de firma al firmante con contractSignatoryId cs111111-… del contrato c1a2b3c4-…”
Entrada (arguments)
{
  "action": "resend_signatory_to_sign",
  "contract_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "contractSignatoryId": "cs111111-2222-3333-4444-555555555555"
}
Respuesta MCP
{
  "contractSignatureId": "cs111111-2222-3333-4444-555555555555",
  "DocumentoId": 884421,
  "signed": false,
  "urlSign": "https://firma.portalfirma.cl/sign/…",
  "Descripcion": "Documento enviado a firmar",
  "ExitoEmail": true
}

action=resend_signatory_to_sign. Obtén los IDs con process_detail_get_by_operation.

Pregunta del usuario · ejemplo 2

“Actualiza el email de la firmante person_id p1234567-… a maria.nueva@ejemplo.cl”
Entrada (arguments)
{
  "action": "update_signatory_data",
  "person_id": "p1234567-89ab-cdef-0123-456789abcdef",
  "email": "maria.nueva@ejemplo.cl"
}
Respuesta MCP
{
  "person_id": "p1234567-89ab-cdef-0123-456789abcdef",
  "rut": "12.345.678-9",
  "name": "María",
  "paternalLastName": "González",
  "maternalLastName": "Pérez",
  "email": "maria.nueva@ejemplo.cl",
  "phone": "+56912345678"
}

action=update_signatory_data. Solo personas que participan en contratos de tu entidad.

Pregunta del usuario · ejemplo 3

“Cambia el tipo de firma del firmante cs111111-… a visada en el contrato c1a2b3c4-…”
Entrada (arguments)
{
  "action": "update_type_signature",
  "contract_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "contractSignatoryId": "cs111111-2222-3333-4444-555555555555",
  "contractEntityPersonId": "cep11111-2222-3333-4444-555555555555",
  "typeSign": "visada"
}
Respuesta MCP
{
  "contractEntityPersonId": "cep11111-2222-3333-4444-555555555555",
  "contractSignatoryId": "cs111111-2222-3333-4444-555555555555",
  "typeSign": "visada",
  "certificationService": "portalfirma"
}

action=update_type_signature. avanzada→cds; visada→portalfirma; enrolada→cds; simple→cds (FES).

Firma masiva

sign_documents_cds_massive_toolswrite

Sign CDS documents

Firma masiva CDS: listar pendientes, pedir código y firmar.

Pregunta del usuario · ejemplo 1

“Lista los documentos pendientes de firma CDS del RUT 12.345.678-9”
Entrada (arguments)
{
  "action": "list_pending",
  "rut": "12.345.678-9"
}
Respuesta MCP
{
  "action": "list_pending",
  "operations": [
    {
      "id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "operation": 482910,
      "stage": "starting",
      "signers": [
        {
          "personId": "p1234567-89ab-cdef-0123-456789abcdef",
          "fullName": "María González Pérez"
        }
      ]
    }
  ],
  "count": 1
}

action=list_pending. Solo operaciones de tu entidad.

Pregunta del usuario · ejemplo 2

“Pide el código SMS/WhatsApp de CDS para firmar la operación 482910 con el RUT 12.345.678-9 (ya tengo la clave del certificado).”
Entrada (arguments)
{
  "action": "request_sign_code",
  "rut": "12.345.678-9",
  "clave_certificado": "••••••••",
  "operations": [482910]
}
Respuesta MCP
{
  "action": "request_sign_code",
  "message": "Código de verificación enviado por WhatsApp/SMS",
  "status": "OK",
  "enrollment": {
    "rut": "12.345.678-9",
    "canSignMassive": true,
    "certificadoras": {
      "cds": { "available": true, "enrolled": true, "vigente": true }
    }
  }
}

action=request_sign_code. Luego el usuario entrega el código y se llama sign_documents.

Pregunta del usuario · ejemplo 3

“Firma la operación 482910 con el código CDS 123456 que me llegó por WhatsApp.”
Entrada (arguments)
{
  "action": "sign_documents",
  "rut": "12.345.678-9",
  "clave_certificado": "••••••••",
  "segundo_factor": "123456",
  "operations": [482910]
}
Respuesta MCP
{
  "action": "sign_documents",
  "results": [
    { "operation": 482910, "signed": true, "error": null }
  ],
  "signedCount": 1,
  "failedCount": 0,
  "remainingPending": { "operations": [], "count": 0 }
}

action=sign_documents. Requiere clave_certificado + segundo_factor + operations del mismo lote.

Wallet

wallet_manage_balance_toolswrite

Manage wallet balance

Consulta o recarga saldo de wallet del partner autenticado.

Pregunta del usuario · ejemplo 1

“¿Cuánto saldo tengo en mi wallet?”
Entrada (arguments)
{
  "action": "get_balance"
}
Respuesta MCP
{
  "action": "get_balance",
  "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": 45000,
  "history": []
}

action=get_balance. La entidad se toma del token.

Pregunta del usuario · ejemplo 2

“Quiero recargar $20.000 a mi wallet. El email para Flow es pagos@miempresa.cl”
Entrada (arguments)
{
  "action": "add_amount_flow",
  "amount": 20000,
  "email": "pagos@miempresa.cl"
}
Respuesta MCP
{
  "action": "add_amount_flow",
  "url": "https://www.flow.cl/app/web/pay.php?token=…",
  "amount": 20000,
  "email": "pagos@miempresa.cl"
}

action=add_amount_flow. El usuario debe abrir la URL para completar el pago.

Templates

template_manage_toolswrite

Manage templates

Busca plantillas, devuelve grupos de campos a completar y envía a firmar (PDF + wallet).

Pregunta del usuario · ejemplo 1

“Busca plantillas de mandato en mi catálogo”
Entrada (arguments)
{
  "action": "search",
  "query": "mandato",
  "top_k": 5
}
Respuesta MCP
{
  "results": [
    {
      "template_version_id": "f8a46d72-2b42-4a52-b9b8-4907d9e24407",
      "name": "Mandato especial",
      "description": "Mandato para representación ante terceros.",
      "url": "https://www.portalfirma.cl/servicios/notaria-virtual/completar/f8a46d72-2b42-4a52-b9b8-4907d9e24407"
    }
  ]
}

action=search. query obligatorio; top_k opcional (1–20, default 5). Usa template_version_id en get_forms.

Pregunta del usuario · ejemplo 2

“¿Qué campos debo completar en esa plantilla de mandato?”
Entrada (arguments)
{
  "action": "get_forms",
  "template_version_id": "f8a46d72-2b42-4a52-b9b8-4907d9e24407"
}
Respuesta MCP
{
  "template_version_id": "f8a46d72-2b42-4a52-b9b8-4907d9e24407",
  "name": "Mandato especial",
  "description": "Mandato para representación ante terceros.",
  "groups": [
    {
      "group": "mandante",
      "type": "signer",
      "variables": [
        {
          "id": "rut_mandante_signer",
          "name": "rut",
          "label": "RUT",
          "type": "signer",
          "input_type": "rut",
          "required": true,
          "synthetic": false
        }
      ]
    }
  ]
}

action=get_forms. template_version_id copiado de search. Pide al usuario cada variable.id.

Pregunta del usuario · ejemplo 3

“Ya tengo los datos del mandante. Envíalo a firmar.”
Entrada (arguments)
{
  "action": "send_sign",
  "template_version_id": "f8a46d72-2b42-4a52-b9b8-4907d9e24407",
  "values": {
    "rut_mandante_signer": "12.345.678-9",
    "email_mandante_signer": "mandante@empresa.cl",
    "telefono_mandante_signer": "+56912345678",
    "nombre_completo_mandante_signer": "JUAN PEREZ GONZALEZ"
  }
}
Respuesta MCP
{
  "processId": "c1a2b3d4-e5f6-7890-abcd-ef1234567890",
  "operation": "482910",
  "createdDateAt": "2026-09-15T18:42:00.000Z",
  "signatories": [
    {
      "alias": "Mandante",
      "rut": "12.345.678-9",
      "email": "mandante@empresa.cl",
      "name": "JUAN PEREZ GONZALEZ"
    }
  ]
}

action=send_sign. values usa los id de get_forms. El servidor genera el PDF y cobra wallet. No enviar HTML.