Plataforma de Engenharia DPconnect · API v1

Documentação Técnica & Referência da API

Integre envio transacional de mensagens WhatsApp, ferramentas HTTP com validação JSON Schema (Ajv), filas de aprovação humana e webhooks assinados com HMAC-SHA256.

Arranque Rápido da Plataforma

01 · ORGANIZAÇÃO & RBAC

Configurar Espaço de Trabalho

Subscreva um plano comercial, crie uma organização isolada e adicione operadores com permissões granulares (OWNER, ADMIN, AGENT, VIEWER).

02 · AGENTE & FERRAMENTAS

Ligar Conectores & Esquemas

Anexe documentos RAG (pgvector), registe conectores REST/PostgreSQL com parâmetros JSON Schema e teste a execução no simulador.

03 · SESSÃO WHATSAPP

Emparelhar Canal QR & Webhooks

Emparelhe a sessão WhatsApp Business via código QR, verifique o estado da ligação e monitorize o trace de execução em tempo real.

1. Autenticação (Chaves de API dpc_)

Tokens Bearer isolados por organização para acesso programático

Gere uma chave de API em Painel → Developer API. As chaves utilizam o prefixo dpc_ e apenas o seu hash SHA-256 é armazenado em repouso. O segredo completo é apresentado apenas uma vez no momento da criação.

Authorization: Bearer dpc_live_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c
Content-Type: application/json

2. Envio de Mensagens & Idempotência

POST /api/v1/developer/messages/send

Envie notificações transacionais, códigos OTP ou avisos de faturação através de um canal WhatsApp ativo da sua organização. Inclua sempre o cabeçalho Idempotency-Key para evitar duplicações em retentativas de rede.

POST /api/v1/developer/messages/send HTTP/1.1
Host: api.dpconnect.online
Authorization: Bearer dpc_live_9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c
Content-Type: application/json
Idempotency-Key: ord-8492-shipped-v1

{
  "to": "258840000000",
  "message": "Order #DP-8492 has been dispatched and will arrive by 16:00.",
  "channelId": "chn_01J9XYZ..."
}
HTTP 202 Accepted (Outbox Transacional)Consulte GET /api/v1/developer/messages/:id para verificar o estado de entrega (SENT, QUEUED ou FAILED).
Proteção de Repetição IdempotenteReenviar a mesma Idempotency-Key devolve o registo existente sem colocar uma segunda mensagem na fila WhatsApp.

3. Ferramentas REST com JSON Schema (Ajv)

Definições determinísticas de ferramentas com políticas de aprovação por risco

Cada ferramenta HTTP associada a um agente é validada contra um JSON Schema estrito antes de qualquer chamada externa. Defina o nível de risco (LOW, HIGH ou CRITICAL) para executar automaticamente ou reter para aprovação humana.

{
  "name": "issue_partial_refund",
  "description": "Issues a partial refund in EUR for a verified customer order",
  "method": "POST",
  "endpoint": "https://api.merchant.eu/v1/orders/{{orderId}}/refund",
  "riskLevel": "HIGH",
  "requiresApproval": true,
  "parametersSchema": {
    "type": "object",
    "required": ["orderId", "amountCents", "reason"],
    "properties": {
      "orderId": { "type": "string", "pattern": "^DP-[0-9]{4,8}$" },
      "amountCents": { "type": "integer", "minimum": 100, "maximum": 50000 },
      "reason": { "type": "string" }
    },
    "additionalProperties": false
  }
}

4. Webhooks Assinados & Proteção SSRF

Os webhooks enviados incluem o cabeçalho X-DPConnect-Signature (HMAC-SHA256). Endereços de loopback, link-local e redes privadas RFC1918 são bloqueados automaticamente em produção.

5. Controlo de Acesso Baseado em Funções (RBAC)

Todos os endpoints aplicam isolamento por organização: OWNER e ADMIN gerem faturação, conectores e chaves API; AGENT opera conversas e aprovações; VIEWER possui acesso de leitura.

Pronto para gerar a sua primeira chave de API?

Aceda à consola de programação para criar chaves dpc_ e testar webhooks.

Abrir Consola de Programador