A API do Apruvly é uma API RESTful JSON. Todas as requisições devem ser autenticadas com uma chave de API. As respostas são sempre JSON, exceto quando o corpo está vazio (204).

URL Base

Exemplo Rápido

Crie um workflow de aprovação com um único passo usando um 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."
      }
    }
  }
}'

Passe sua chave de API no cabeçalho Authorization como um Bearer token. Você pode criar e gerenciar chaves de API pelo painel.

Formato do cabeçalho

Authorization: Bearer wf_YOUR_API_KEY

Você pode gerar uma chave de API na seção Chaves de API do painel.

Cria um novo workflow de aprovação e inicia imediatamente o primeiro passo.

Corpo da Requisição

Exemplo de Requisição

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."
      }
    }
  }
}'

Exemplo de Resposta 202 Accepted

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

Associe sua própria referência de negócio (número de contrato, ticket do CRM, id de deploy) ao criar um workflow e consulte o status ou cancele sem guardar o UUID da plataforma. Requer plano Growth ou superior. Máx. 128 caracteres; permitidos: letras, dígitos e . _ : / -. Único por conta.

Exemplo de Resposta 402 Payment Required

{
  "success": false,
  "message": "Seu plano não inclui external_id. Faça upgrade para Growth ou superior para associar um identificador de negócio aos workflows."
}

Criar Workflow — Exemplo de Requisição

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."
      }
    }
  }
}'

Exemplo de Resposta 202 Accepted

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

Consultar por external_id — Exemplo de Requisição

Retorna o mesmo payload de GET /workflow/{id}, buscando pelo external_id informado na criação. Requer plano Growth ou superior.

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

Exemplo de Resposta 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 Workflow — Exemplo de Requisição

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

Exemplo de Resposta 200 OK

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

Listar Workflows — Exemplo de Requisição

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

Exemplo de Resposta 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 uma configuração de workflow sem criá-lo. Útil para verificar o payload antes de enviá-lo.

Exemplo de Requisição

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."
      }
    }
  }
}'

Exemplo de Resposta 200 OK

{
  "success": true
}

Retorna o estado completo de um workflow, incluindo o log de atividades e o histórico de decisões.

Parâmetros de Caminho

Exemplo de Requisição

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

Exemplo de Resposta 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"
      }
    ]
  }
}

Retorna uma lista paginada de workflows pertencentes ao usuário autenticado.

Parâmetros de Consulta

Exemplo de Requisição

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

Exemplo de Resposta 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
    }
  ]
}

Retorna os workflows criados mais recentemente para o usuário autenticado.

Exemplo de Requisição

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

Retorna assinatura, plano, saldo de créditos e resumo de uso do usuário autenticado.

Exemplo de Requisição

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

Gerencie credenciais de canais de terceiros (Slack, MS Teams, Twilio, etc.) via a API REST.

Cancela um workflow pendente. Workflows concluídos ou expirados não podem ser cancelados.

Você também pode cancelar pelo identificador de negócio definido na criação — veja Identificadores de correlação (external_id). Identificadores de correlação (external_id)

Parâmetros de Caminho

Exemplo de Requisição

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

Exemplo de Resposta 200 OK

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

Registra uma decisão de aprovação ou rejeição para uma etapa do workflow. A ação (aprovar ou rejeitar) é determinada pelo sufixo do caminho da URL, não pelo corpo da requisição. Nenhum corpo de requisição é necessário.

Parâmetros de Caminho

Exemplo de Requisição

# 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"

Exemplo de Resposta 200 OK

{
  "success": true
}

Gerencia a agenda de áreas (times) e pessoas. Contatos alimentam fallback de e-mail nas notificações e vinculam destinatários para análise cross-channel.

Áreas

Pessoas

Exemplo de Requisição — Cria uma pessoa com áreas e contatos.

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" }
    ]
  }'

Exemplo de Resposta 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" }
    ]
  }
}

Operações em lote

Os endpoints em lote recebem uma lista no campo "items". A criação tem limite por requisição (100 áreas, 1.000 pessoas) e a atualização é limitada a duas vezes o tamanho que o plano do cliente suporta para o recurso correspondente.

Exemplo de Requisição — Cria até 1.000 pessoas em uma única chamada (com vínculos e contatos).

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" }
        ]
      }
    ]
  }'

Exemplo de Resposta 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": ["…"] }
    ]
  }
}

O lote é processado em conjunto: se qualquer item for inválido, a requisição é rejeitada e nada é gravado.

Escopos necessários

Cada endpoint exige o escopo correspondente na API key. Conceda escopos em Chaves de API no painel.

Formatos de endereço por canal

Cada contato é um par (provider, address). Só providers configurados em /integrations (além de e-mail) são aceitos.

Robôs de grupo DingTalk não ficam no diretório — eles enviam para um grupo, não para um contato individual.

Erros

Use o campo `on` para registrar ações em eventos de ciclo de vida do workflow. Cada ação tem um tipo (webhook, email ou twilio-sms) e um payload de dados. Quando o evento dispara, todas as ações são executadas em ordem.

Formas wrapped e flat

Cada action é um objeto JSON que pode ser serializado em duas formas. A forma wrapped ({"type":"...", "data":{...}}) é a canônica produzida pela API e a única aceita para twilio-sms. A forma flat infere o tipo a partir dos campos do payload (url → webhook, to → email) e é mantida por compatibilidade com clientes antigos.

{
  "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 do ciclo de vida

WebhookAction — type: "webhook"

Envia uma requisição HTTP para um endpoint externo. Hosts privados e de loopback são rejeitados no momento do envio.

EmailAction — type: "email"

Envia um email pelo SMTP customizado (quando configurado) ou pelo postman do sistema.

SmsAction — type: "twilio-sms"

Dispara um SMS fire-and-forget via Twilio. Apenas informativo — sem correlação por short-code nem rastreio de resposta.

Interpolação de Variáveis

Você pode usar as seguintes variáveis dentro dos valores do body do webhook. Elas são substituídas automaticamente no momento da execução.

Exemplo de Requisição

{
  "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}"
          }
        }
      }
    ]
  }
}

Ações por Step

Além dos eventos no nível do workflow, cada step pode registrar suas próprias ações que disparam quando AQUELE step é aprovado ou rejeitado — independente do resultado final do workflow. Use `step.actions.approved` e `step.actions.rejected` para disparar webhooks ou emails por decisão.

{
  "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"
            }
          }
        ]
      }
    }
  }
}

Custo: cada webhook conta como 1 crédito; cada destinatário em ações de email ou twilio-sms conta como 1 crédito por destinatário. CC e BCC em ações de email não são cobrados.

Custo em créditos

Cada step custa 1 crédito mais 1 por nível de escalonamento configurado. Actions de envio externo adicionam um único crédito flat, compartilhado entre webhook e twilio-sms.

Os créditos são debitados uma única vez no momento da criação do workflow. Não há cobrança por disparo.

Step

Channel delivery

A entrega em canal compartilhado publica uma mensagem de aprovação em canal de equipe, grupo ou chat. Apenas usuários em allowList podem clicar nos botões interativos; o log registra quem clicou, não o ID do canal.

CardOverride

EmailData — usado quando type = email

Variáveis do corpo do e-mail

Estes placeholders podem ser usados no assunto e no corpo.

SlackData — usado quando type = slack

MSTeamsData — usado quando type = ms-teams

WhatsAppData — usado quando type = whatsapp

TelegramData — usado quando type = telegram

DiscordData — usado quando type = discord

DingTalkData — usado quando type = dingtalk

TwilioSMSData — usado quando type = twilio-sms

TwilioWhatsAppData — usado quando type = twilio-whatsapp

Escalation

Decision — retornado dentro de decisions[] em GET /workflow/{id}

SMTP personalizado (integração da conta)

Planos Business e Professional podem enviar e-mails de aprovação pelo seu SMTP em vez do mailer da plataforma. Configure em Configurações → Integrações → SMTP personalizado (não no JSON do workflow).

• Host, porta, remetente e usuário/senha opcionais. Use Enviar e-mail de teste antes de workflows em produção.
• Porta 587 com STARTTLS (interruptor TLS desligado) ou porta 465 com TLS implícito (interruptor TLS ligado). IPs privados e reservados são bloqueados.
• Use um remetente que seu servidor aceite relayar (em geral uma caixa em domínio com SPF/DKIM autenticado).
• Credenciais criptografadas em repouso (AES-256-GCM). Conexões exigem TLS 1.2+. E-mails de teste vão apenas para o e-mail da sua conta.
• Entrega, bounces e alinhamento SPF/DKIM/DMARC são impostos pelo seu servidor SMTP — a Apruvly não verifica o domínio de envio.

Regras de Identificador de Etapa

As chaves de etapa (usadas nos campos start, approved e rejected, e como chaves do mapa workflow) devem corresponder ao seguinte padrão - letra minúscula seguida de letras minúsculas, dígitos, hífens ou underscores:

Formato de Duração

Durações são expressas como um número seguido de um sufixo de unidade:

A expiração do workflow deve estar entre 5 minutos (mínimo) e 7 dias (máximo).

O endpoint MCP segue a especificação do Model Context Protocol usando JSON-RPC 2.0 sobre HTTP. Permite que agentes de IA e ferramentas de automação pausem a execução e solicitem aprovação humana antes de realizar ações críticas.

Endpoint

Autenticação Obrigatório

Authorization: Bearer wf_YOUR_API_KEY
Content-Type: application/json

Descoberta Opcional

Clientes MCP-aware podem buscar um documento de descoberta público em GET /.well-known/mcp para auto-detectar a URL do endpoint, transports e versões de protocolo suportadas, esquema de autenticação, e o catálogo de ferramentas disponíveis. Não requer autenticação.

{
  "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"]
}

Como 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": {}
    }
  }'