La API de Apruvly es una API JSON RESTful. Todas las solicitudes deben autenticarse con una clave de API. Las respuestas son siempre JSON, salvo cuando la respuesta está vacía (204).

URL base

Ejemplo rápido

Crea un flujo de aprobación de un solo paso con un único comando curl:

curl -X POST https://api.apruvly.io/api/v1/workflow \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Q1 Marketing Budget",
    "description": "Marketing budget for Q1, $18k total"
  },
  "expires": "48h",
  "start": "step1",
  "workflow": {
    "step1": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Q1 Marketing Budget – $18k",
        "body": "Please review the budget breakdown in the linked document and share your decision."
      }
    }
  }
}'

Pasa tu clave de API en el encabezado Authorization como token Bearer. Puedes crear y gestionar claves de API desde el panel.

Formato del encabezado

Authorization: Bearer wf_YOUR_API_KEY

Puedes generar una clave de API desde la sección Claves de API del panel.

Crea un nuevo flujo de aprobación e inicia de inmediato el primer paso.

Cuerpo de la solicitud

Solicitud de ejemplo

curl -X POST https://api.apruvly.io/api/v1/workflow \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Contract Sign-off",
    "description": "Legal review for client contract #4821",
    "links": ["https://drive.example.com/contracts/4821"],
    "tags": ["legal", "contract"]
  },
  "external_id": "CONTRACT-2025-0042",
  "expires": "72h",
  "start": "legal-review",
  "workflow": {
    "legal-review": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Approval Request: Contract #4821",
        "body": "Please review and approve contract #4821."
      },
      "approved": "ceo-approval",
      "escalation": {
        "type": "email",
        "after": "24h",
        "data": {
          "to": ["[email protected]"],
          "subject": "Escalation: Contract #4821 pending approval",
          "body": "Contract #4821 has not been reviewed. Please take action."
        }
      }
    },
    "ceo-approval": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Final Approval: Contract #4821",
        "body": "Legal review is complete. Please provide final approval."
      }
    }
  }
}'

Respuesta de ejemplo 202 Accepted

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "CONTRACT-2025-0042"
  }
}

Asocia tu propia referencia de negocio (número de contrato, ticket de CRM, id de despliegue) al crear un flujo de trabajo, y luego consulta su estado o cancélalo sin almacenar el UUID de la plataforma. Requiere el plan Growth o superior. Máx. 128 caracteres; permitidos: letras, dígitos y . _ : / -. Único por cuenta.

Respuesta de ejemplo 402 Payment Required

{
  "success": false,
  "message": "Tu plan no incluye external_id. Mejora a Growth o superior para asociar un id de correlación de negocio a los flujos de trabajo."
}

Crear flujo de trabajo — Solicitud de ejemplo

curl -X POST https://api.apruvly.io/api/v1/workflow \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Contract Sign-off",
    "description": "Legal review for client contract #4821"
  },
  "external_id": "CONTRACT-2025-0042",
  "expires": "72h",
  "start": "legal-review",
  "workflow": {
    "legal-review": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Approval Request: Contract #4821",
        "body": "Please review and approve contract #4821."
      }
    }
  }
}'

Respuesta de ejemplo 202 Accepted

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "CONTRACT-2025-0042"
  }
}

Obtener por external_id — Solicitud de ejemplo

Devuelve la misma carga que GET /workflow/{id}, buscado por el external_id suministrado al crearlo. Requiere el plan Growth o superior.

curl https://api.apruvly.io/api/v1/workflow/external/CONTRACT-2025-0042 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true,
  "data": {
    "id":                  "550e8400-e29b-41d4-a716-446655440000",
    "externalId":          "CONTRACT-2025-0042",
    "status":              "pending",
    "currentStep":         "legal-review",
    "createdAt":           "2025-01-15T10:00:00Z",
    "expiresAt":           "2025-01-18T10:00:00Z",
    "decisions": []
  }
}

Cancelar flujo de trabajo — Solicitud de ejemplo

curl -X DELETE https://api.apruvly.io/api/v1/workflow/external/CONTRACT-2025-0042 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Listar flujos de trabajo — Solicitud de ejemplo

curl "https://api.apruvly.io/api/v1/workflows/search?external_id=CONTRACT-2025-0042" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true,
  "data": [
    {
      "id":             "550e8400-e29b-41d4-a716-446655440000",
      "title":          "Contract Sign-off",
      "external_id":    "CONTRACT-2025-0042",
      "current_status": "pending",
      "current_step":   "legal-review",
      "created_at":     "2025-01-15T10:00:00Z",
      "expires_at":     "2025-01-18T10:00:00Z",
      "completed_at":   null
    }
  ]
}

Valida la configuración de un flujo de trabajo sin crearlo. Útil para comprobar tu carga antes de enviarla.

Solicitud de ejemplo

curl -X POST https://api.apruvly.io/api/v1/workflow/validate \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "object": {
    "title": "Test Workflow"
  },
  "expires": "24h",
  "start": "step1",
  "workflow": {
    "step1": {
      "type": "email",
      "data": {
        "to": ["[email protected]"],
        "subject": "Test Approval",
        "body": "Please approve this test request."
      }
    }
  }
}'

Respuesta de ejemplo 200 OK

{
  "success": true
}

Recupera el estado completo de un flujo de trabajo, incluido su registro de actividad y su historial de decisiones.

Parámetros de ruta

Solicitud de ejemplo

curl https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true,
  "data": {
    "id":                  "550e8400-e29b-41d4-a716-446655440000",
    "externalId":          "CONTRACT-2025-0042",
    "status":              "pending",
    "currentStep":         "ceo-approval",
    "currentEscalation":  0,
    "createdAt":           "2025-01-15T10:00:00Z",
    "expiresAt":           "2025-01-18T10:00:00Z",
    "nextTickAt":          "2025-01-16T10:00:00Z",
    "decisions": [
      {
        "user":        "[email protected]",
        "is_approved": true,
        "ip":          "203.0.113.42",
        "decisionAt":  "2025-01-15T14:22:00Z"
      }
    ]
  }
}

Devuelve una lista paginada de los flujos de trabajo que pertenecen al usuario autenticado.

Parámetros de consulta

Solicitud de ejemplo

curl "https://api.apruvly.io/api/v1/workflows/search?status=pending&query=contract" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true,
  "data": [
    {
      "id":             "550e8400-e29b-41d4-a716-446655440000",
      "title":          "Contract Sign-off",
      "external_id":    "CONTRACT-2025-0042",
      "current_status": "pending",
      "current_step":   "ceo-approval",
      "created_at":     "2025-01-15T10:00:00Z",
      "expires_at":     "2025-01-18T10:00:00Z",
      "completed_at":   null
    }
  ]
}

Devuelve los flujos de trabajo creados más recientemente para el usuario autenticado.

Solicitud de ejemplo

curl "https://api.apruvly.io/api/v1/workflows/recent" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Devuelve la suscripción, el plan, el saldo de créditos y el resumen de uso del usuario autenticado.

Solicitud de ejemplo

curl "https://api.apruvly.io/api/v1/billing" \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Gestiona las credenciales de canales de terceros (Slack, MS Teams, Twilio, etc.) a través de la API REST.

Cancela un flujo de trabajo pendiente. Los flujos completados o caducados no se pueden cancelar.

También puedes cancelar por el id de negocio que estableciste al crearlo: consulta IDs de correlación de negocio (external_id). IDs de correlación de negocio (external_id)

Parámetros de ruta

Solicitud de ejemplo

curl -X DELETE https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Registra una decisión de aprobación o rechazo para un paso del flujo de trabajo. La acción (aprobar o rechazar) se determina por el sufijo de la ruta de la URL, no por el cuerpo de la solicitud. No se requiere cuerpo de solicitud.

Parámetros de ruta

Solicitud de ejemplo

# Approve
curl -X PUT https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000/7a9f1c2d-4b3e-48f6-9d8c-1a2b3c4d5e6f/approve \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

# Reject
curl -X PUT https://api.apruvly.io/api/v1/workflow/550e8400-e29b-41d4-a716-446655440000/7a9f1c2d-4b3e-48f6-9d8c-1a2b3c4d5e6f/reject \
  -H "Authorization: Bearer wf_YOUR_API_KEY"

Respuesta de ejemplo 200 OK

{
  "success": true
}

Gestiona tu libreta de direcciones de áreas (equipos) y personas. Los contactos alimentan el respaldo por correo en el momento de la notificación y vinculan a los destinatarios para las analíticas entre canales.

Áreas

Personas

Solicitud de ejemplo — Crea una persona con pertenencias y contactos.

curl -X POST https://api.apruvly.io/api/v1/directory/people \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Ana Souza",
    "area_ids": ["6c2b6e80-1f74-4cf2-9e2f-0d0e3b9b0001"],
    "contacts": [
      { "provider": "email", "address": "[email protected]", "label": "work" },
      { "provider": "twilio-sms", "address": "+5511999999999" }
    ]
  }'

Respuesta de ejemplo 201 Created

{
  "success": true,
  "data": {
    "id": "a4d1f0c6-2d24-49b3-9e3c-7a2e6c4b0001",
    "display_name": "Ana Souza",
    "is_active": true,
    "area_ids": ["6c2b6e80-1f74-4cf2-9e2f-0d0e3b9b0001"],
    "contacts": [
      { "id": "…", "provider": "email", "address": "[email protected]", "label": "work" },
      { "id": "…", "provider": "twilio-sms", "address": "+5511999999999" }
    ]
  }
}

Operaciones masivas

Los endpoints masivos aceptan un array de elementos bajo un único campo «items». La creación está limitada por solicitud (100 áreas, 1000 personas) y las actualizaciones se limitan al doble del tamaño del plan del cliente para el recurso correspondiente.

Solicitud de ejemplo — Crea hasta 1000 personas en una sola llamada (con sus pertenencias y contactos).

curl -X POST https://api.apruvly.io/api/v1/directory/people/bulk \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "display_name": "Ana Souza",
        "area_ids": ["6c2b6e80-1f74-4cf2-9e2f-0d0e3b9b0001"],
        "contacts": [
          { "provider": "email", "address": "[email protected]", "label": "work" }
        ]
      },
      {
        "display_name": "Bruno Lima",
        "contacts": [
          { "provider": "twilio-sms", "address": "+5511988887777" }
        ]
      }
    ]
  }'

Respuesta de ejemplo 201 Created

{
  "success": true,
  "data": {
    "count": 2,
    "items": [
      { "id": "a4d1f0c6-…", "display_name": "Ana Souza", "area_ids": ["6c2b6e80-…"], "contacts": ["…"] },
      { "id": "f10b2e8a-…", "display_name": "Bruno Lima", "area_ids": [], "contacts": ["…"] }
    ]
  }
}

Todo el lote se procesa junto: si una sola entrada no es válida, la solicitud se rechaza y no se guarda nada.

Ámbitos requeridos

Cada endpoint requiere el ámbito de clave de API correspondiente. Concede los ámbitos en Claves de API en la consola.

Formatos de dirección de contacto

Cada contacto es un par (proveedor, dirección). Solo se aceptan los proveedores configurados en /integrations (además del correo).

Los robots de grupo de DingTalk no se almacenan en el directorio: difunden a un grupo, no a un contacto individual.

Errores

Usa el campo `on` para registrar acciones para los eventos del ciclo de vida del flujo de trabajo. Cada acción tiene un tipo (webhook, email o twilio-sms) y una carga de datos. Cuando se dispara un evento, todas las acciones se ejecutan en orden.

Formas envuelta y plana

Cada acción es un objeto JSON que puede serializarse de dos formas. La forma envuelta ({"type":"...", "data":{...}}) es la forma canónica que produce la API y la única aceptada para twilio-sms. La forma plana infiere el tipo a partir de los campos de la carga (url → webhook, to → email) y se mantiene por compatibilidad con versiones anteriores.

{
  "on": {
    "workflow_approved": [
      { "type": "webhook",    "data": { "url": "https://example.com/hooks/approved", "method": "POST" } },
      { "type": "email",      "data": { "to": ["[email protected]"], "subject": "Approved", "body": "Workflow ${id} is approved." } },
      { "type": "twilio-sms", "data": { "to": ["+14155552671"], "body": "Workflow ${id} approved" } }
    ]
  }
}

Eventos del ciclo de vida

WebhookAction — type: "webhook"

Envía una solicitud HTTP a un endpoint externo. Los hosts privados y de bucle invertido se rechazan en el momento del envío.

EmailAction — type: "email"

Envía un correo a través de tu SMTP personalizado (cuando está configurado) o el mensajero del sistema.

SmsAction — type: "twilio-sms"

Envía un SMS de tipo «dispara y olvida» a través de Twilio. Solo informativo: sin correlación de códigos cortos ni seguimiento de respuestas.

Interpolación de variables

Puedes usar las siguientes variables dentro de los valores del cuerpo del webhook. Se reemplazan automáticamente en el momento de la ejecución.

Solicitud de ejemplo

{
  "on": {
    "workflow_approved": [
      {
        "type": "webhook",
        "data": {
          "url":     "https://api.yourapp.com/webhooks/approved",
          "method":  "POST",
          "headers": { "Authorization": "Bearer your-token" },
          "body": {
            "workflow_id":  "${id}",
            "status":       "${status}",
            "current_step": "${current_step}"
          },
          "timeout": "30s"
        }
      }
    ],
    "workflow_rejected": [
      {
        "type": "webhook",
        "data": {
          "url":   "https://api.yourapp.com/webhooks/rejected",
          "async": true
        }
      }
    ],
    "step_approved": [
      {
        "type": "webhook",
        "data": {
          "url":  "https://api.yourapp.com/webhooks/step-done",
          "body": {
            "step": "${current_step}"
          }
        }
      }
    ]
  }
}

Acciones por paso

Además de los eventos a nivel de flujo de trabajo, cada paso puede registrar sus propias acciones que se disparan cuando ESE paso se aprueba o se rechaza, independientemente del resultado final del flujo. Usa `step.actions.approved` y `step.actions.rejected` para activar webhooks o correos por decisión.

{
  "workflow": {
    "review": {
      "type": "email",
      "data": {
        "to":      ["[email protected]"],
        "subject": "Please review",
        "body":    "Approve or reject ${id}"
      },
      "actions": {
        "approved": [
          {
            "type": "webhook",
            "data": {
              "url":    "https://example.com/hooks/review-approved",
              "method": "POST"
            }
          }
        ],
        "rejected": [
          {
            "type": "email",
            "data": {
              "to":      ["[email protected]"],
              "subject": "Review rejected",
              "body":    "${id} was rejected"
            }
          }
        ]
      }
    }
  }
}

Coste: cada webhook cuenta como 1 crédito; cada destinatario en acciones de email o twilio-sms cuenta como 1 crédito por destinatario. Las CC y CCO en acciones de correo no se cobran.

Coste en créditos

Cada paso cuesta 1 crédito más 1 por cada nivel de escalado configurado. Las acciones de entrega externa añaden un único recargo fijo compartido entre webhook y twilio-sms.

Los créditos se debitan una sola vez al crear el flujo de trabajo. No hay cargo por envío.

Step

Channel delivery

La entrega por canal compartido publica un único mensaje de aprobación en un canal, grupo o chat de equipo. Solo los usuarios incluidos en allowList pueden hacer clic en los botones interactivos de Aprobar/Rechazar; el registro de decisiones anota a quien hace clic, no el ID del canal.

CardOverride

EmailData — usado cuando type = email

Variables del cuerpo del correo

Estos marcadores de posición se pueden usar en los campos de asunto y cuerpo.

SlackData — usado cuando type = slack

MSTeamsData — usado cuando type = ms-teams

WhatsAppData — usado cuando type = whatsapp

TelegramData — usado cuando type = telegram

DiscordData — usado cuando type = discord

DingTalkData — usado cuando type = dingtalk

TwilioSMSData — usado cuando type = twilio-sms

TwilioWhatsAppData — usado cuando type = twilio-whatsapp

Escalation

Decision — devuelto dentro de decisions[] en GET /workflow/{id}

SMTP personalizado (integración de cuenta)

Los planes Business y Professional pueden enviar correos de aprobación a través de tu propio servidor SMTP en lugar del mensajero de la plataforma. Configúralo en Ajustes → Integraciones → SMTP personalizado (no en el JSON del flujo de trabajo).

• Host, puerto, dirección De y, opcionalmente, usuario/contraseña. Usa Enviar correo de prueba antes de guardar flujos de trabajo de producción.
• Puerto 587 con STARTTLS (interruptor TLS desactivado) o puerto 465 con TLS implícito (interruptor TLS activado). Se bloquean los destinos de IP privadas y reservadas.
• Usa una dirección De que tu servidor tenga permiso para retransmitir (normalmente un buzón en un dominio que autenticas con SPF/DKIM).
• Las credenciales se cifran en reposo (AES-256-GCM). Las conexiones salientes requieren TLS 1.2+. Los correos de prueba se envían solo al correo de tu cuenta.
• La entrega, los rebotes y la alineación SPF/DKIM/DMARC los aplica tu servidor SMTP: Apruvly no verifica tu dominio de envío.

Reglas del identificador de paso

Las claves de paso (usadas en los campos start, approved y rejected, y como claves del mapa workflow) deben coincidir con el siguiente patrón: una letra minúscula seguida de letras minúsculas, dígitos, guiones o guiones bajos:

Formato de duración

Las duraciones se expresan como un número seguido de un sufijo de unidad:

La caducidad del flujo de trabajo debe estar entre 5 minutos (mínimo) y 7 días (máximo).

El endpoint MCP sigue la especificación del Model Context Protocol usando JSON-RPC 2.0 sobre HTTP. Permite que los agentes de IA y las herramientas de automatización pausen la ejecución y soliciten aprobación humana antes de realizar acciones críticas.

Endpoint

Autenticación Obligatorio

Authorization: Bearer wf_YOUR_API_KEY
Content-Type: application/json

Descubrimiento Opcional

Los clientes compatibles con MCP pueden obtener un documento de descubrimiento público en GET /.well-known/mcp para detectar automáticamente la URL del endpoint, los transportes y versiones de protocolo compatibles, el esquema de autenticación y el catálogo de herramientas disponibles. No requiere autenticación.

{
  "endpoint": "https://mcp.apruvly.io/mcp",
  "transports": ["streamable-http"],
  "protocolVersions": ["2025-03-26"],
  "auth": { "scheme": "bearer" },
  "tools": ["create_approval_request", "get_approval_status", "cancel_approval_request"]
}

Cómo funciona

• Claude Code
• Claude Desktop
• Cursor
• VS Code
• curl

{
  "mcpServers": {
    "apruvly": {
      "type": "streamable-http",
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "apruvly": {
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "apruvly": {
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

// .vscode/mcp.json
{
  "servers": {
    "apruvly": {
      "type": "http",
      "url": "https://mcp.apruvly.io/mcp",
      "headers": {
        "Authorization": "Bearer wf_YOUR_API_KEY"
      }
    }
  }
}

curl -X POST https://mcp.apruvly.io/mcp \
  -H "Authorization: Bearer wf_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": {"name": "my-agent", "version": "1.0"},
      "capabilities": {}
    }
  }'