API de Integração

Introdução

A API de integração é agnóstica de sistema de origem — não assume Protheus, SAP, RM ou qualquer ERP específico. Quem fala a língua de um sistema específico é um conector (agente) que você mantém, fora do aprovaAI, traduzindo entre o seu sistema e este contrato.

O aprovaAI nunca inicia conexão com o seu sistema. Ele só recebe chamadas autenticadas e responde — buscar dados na origem e escrever o resultado de volta é responsabilidade do seu conector.

Uma solicitação criada por esta API se comporta como qualquer outra a partir daí: passa pelo motor de workflow configurado no tenant, aparece nas listagens do aprovaAI, gera notificações in-app/push/e-mail para os aprovadores, e tem comentários e histórico.

https://aprovaai.cyberpolos.net

Autenticação

Cada conexão de integração recebe uma API key no formato <connectionId>.<secret>, exibida uma única vez no momento em que a credencial é criada — o aprovaAI não guarda nem reexibe o segredo em texto puro depois disso. Envie em todas as chamadas como Bearer token:

Authorization: Bearer cm3xh2j4k0001abcd.k7f9QpX2yT8vR1nZmW3sLd

A credencial enxerga só o próprio tenant, e só pode criar solicitações de tipos habilitados para integração (ver requestTypeKey em Criar solicitação). No piloto, a emissão de credenciais é feita pela equipe aprovaAI — fale com o seu contato para receber a sua.

Idempotência

Toda solicitação criada é identificada pelo par externalSystem + externalRef que você envia. Se o seu conector reenviar a mesma criação — por retry após timeout, ou reprocessamento — o aprovaAI nunca duplica: devolve a solicitação já existente.

Erros

Toda resposta de erro (4xx/5xx) segue o mesmo formato, com um código estável para tratamento programático e uma mensagem legível:

{
  "error": {
    "code": "requester_not_found",
    "message": "Nenhum usuário com este e-mail neste tenant."
  }
}

Códigos mais comuns, entre os endpoints:

Endpoints

curl -X POST https://aprovaai.cyberpolos.net/api/integrations/requests \
  -H "Authorization: Bearer <connectionId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSystem": "protheus",
    "externalRef": { "branch": "01", "docType": "SC7", "key": "000123" },
    "requestTypeKey": "pedido_de_compra",
    "title": "Pedido de Compra 000123 — Dell Brasil",
    "amountCents": 600000,
    "requesterEmail": "solicitante@empresa.com",
    "customFields": { "fornecedor": "Dell Brasil", "justificativa": "Notebooks para o time" }
  }'

{
  "requestId": "cmr1a2b3c4d5",
  "status": "pending",
  "url": "https://aprovaai.cyberpolos.net/requests/cmr1a2b3c4d5"
}

curl "https://aprovaai.cyberpolos.net/api/integrations/decisions?since=$CURSOR" \
  -H "Authorization: Bearer <connectionId>.<secret>"

{
  "decisions": [
    {
      "requestId": "cmr1a2b3c4d5",
      "externalSystem": "protheus",
      "externalRef": { "branch": "01", "docType": "SC7", "key": "000123" },
      "status": "approved",
      "decidedAt": "2026-07-19T18:00:00Z",
      "decidedExternally": false,
      "history": [
        { "step": "Aprovação do Gestor", "decision": "approved",
          "approverEmail": "gestor@empresa.com", "comment": null }
      ]
    }
  ],
  "nextCursor": "MjAyNi0wNy0xOVQxODowMDowMC4wMDBafGNtcjFhMmIzYzRkNQ"
}

{ "ok": true, "tenant": "empresa-demo", "connection": "ERP Produção" }

curl -X POST https://aprovaai.cyberpolos.net/api/integrations/requests/cmr1a2b3c4d5/status \
  -H "Authorization: Bearer <connectionId>.<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled",
    "reason": "Pedido cancelado pelo comprador direto no Protheus"
  }'

{ "requestId": "cmr1a2b3c4d5", "status": "cancelled" }

Aprovação via API

Aprovar uma solicitação sem passar pelos aprovadores nomeados do aprovaAI é uma decisão de governança, não só técnica — por padrão, essa credencial não pode fazer isso. allowExternalApproval = false

Quando habilitada explicitamente para uma credencial, uma aprovação enviada por POST .../status continua contando como aprovada em todos os fluxos e relatórios, mas fica marcada como decidedExternally: true e visualmente destacada na interface do aprovaAI — distinta de uma aprovação que passou pelos aprovadores do workflow.

Fluxo de integração recomendado

1. Guarde a API key recebida com segurança — ela não é reexibida.
2. Traduza cada documento do seu sistema para o payload de POST /requests (a forma de mapear campos é específica do seu sistema de origem).
3. Persista localmente a relação entre a chave do documento na origem e o requestId retornado.
4. Faça polling periódico de GET /decisions, persistindo o nextCursor a cada chamada.
5. Aplique a decisão de volta no seu sistema, com sua própria lógica de retry — o aprovaAI não sabe se essa escrita teve sucesso.
6. Se o documento de origem for cancelado, negado ou aprovado fora do aprovaAI depois de sincronizado, chame POST .../status para refletir isso — sem esse passo, a solicitação fica pendente indefinidamente.