Documentação técnica

API &
Webhooks.

REST simples, autenticada por key. Webhooks outbound assinados. Sem SDK, sem ceremony — curl direto funciona. Pra Zapier, Make, seu ERP ou scripts.

Quick start Endpoints Webhooks Guia Zapier

Em 60 segundos

Quick start.

1.Vá em Configurações → Integrações e crie uma API key. O sistema mostra a key bruta uma vez — copie pro seu gerenciador de senhas.
2.Adicione a key no header Authorization: Bearer drap_live_… (ou x-api-key) de toda chamada.
3.Pronto. As rotas vivem em https://empresa.drap.app.br/api/v1/* e respondem JSON.

Primeira chamada

curl https://empresa.drap.app.br/api/v1/lancamentos \
  -H "Authorization: Bearer drap_live_xxxxxxxxxxxxxxxxxxxxxx"

# Resposta
{
  "items": [ ... ],
  "total": 142,
  "limit": 100,
  "offset": 0
}

Criando um lançamento

curl -X POST https://empresa.drap.app.br/api/v1/lancamentos \
  -H "Authorization: Bearer drap_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "data": "2026-06-22",
    "descricao": "Venda site",
    "tipo": "receita",
    "valor": 1500.00,
    "contraparte": "ACME Ltda",
    "status": "pago"
  }'

Autenticação

Bearer token no header. Formato: drap_live_ + 32 chars. Cada key fica vinculada a um único tenant.

Rate-limit

60 req/min por API key. Excesso retorna 429 com Retry-After. Crie mais de uma key se precisar de banda separada por integração.

Isolamento

Toda query filtra automaticamente por tenant da key. Sua key nunca vê dados de outra empresa — RLS + filtro explícito no backend.

Escopos

Cada key carrega escopos no formato recurso:ação. Dentro de um recurso eles são hierárquicos: delete inclui write, que inclui read. Falta de escopo responde 403 insufficient-scope dizendo qual escopo faltou.

Recurso	Escopos	Autoriza
Lançamentos	lancamentos:read · write · delete	GET · POST/PATCH · DELETE
Parceiros	parceiros:read · write · delete	GET · POST/PATCH · DELETE
Categorias	categorias:read · write	GET · POST
Cobranças	cobrancas:read · write	GET · POST
Webhooks	webhooks:read · write · delete	GET · POST · DELETE

Cobrança e webhook ficam fora dos escopos legados e dos presets. Uma emite boleto e PIX de verdade na conta Asaas da empresa; a outra manda o dado da empresa pra uma URL. Só entram numa key quando alguém marca isso na emissão — nenhuma key existente ganhou esses poderes quando as rotas nasceram.

Keys criadas antes dos escopos granulares usam read ou write e continuam valendo com o mesmo alcance de sempre — write autoriza também o DELETE. Pra conceder menos que isso, crie uma key nova em Configurações → Integrações. Lá também dá pra definir validade; key vencida responde 401 expired-api-key.

Reference

Endpoints.

Tudo abaixo de /api/v1. Respostas seguem o padrão { items, total } em listas e { item } em single-resource.

Lançamentos

Receitas e despesas do seu fluxo.

GET/lancamentosLista (filtros opcionais)
POST/lancamentosCria
GET/lancamentos/{id}Busca um
PATCH/lancamentos/{id}Atualiza
DELETE/lancamentos/{id}Remove

Filtros em GET: tipo, status, data_de, data_ate, centro_custo, limit, offset.

centro_custo compara texto exato, do jeito que foi gravado. É o campo pra recortar o resultado por obra, projeto ou filial quando a integração usa uma convenção própria de nome.

Parceiros

Clientes, fornecedores e ambos.

GET/parceirosLista (filtros opcionais)
POST/parceirosCria
GET/parceiros/{id}Busca um
PATCH/parceiros/{id}Atualiza
DELETE/parceiros/{id}Remove

Filtros em GET: tipo, ativo, limit, offset.

Categorias

Áreas e subcategorias usadas na classificação.

GET/categoriasLista
POST/categoriasCria nova área

Cobranças

Boleto, PIX e cartão na sua conta Asaas.

GET/cobrancasLista (filtros opcionais)
POST/cobrancasEmite cobrança
GET/cobrancas/{id}Detalhe e situação

Filtros em GET: status, parceiro_id, limit, offset. Exige o módulo Cobranças ativo e a conta Asaas conectada.

Mande Idempotency-Key no POST. Um timeout depois de o Asaas aceitar deixa você sem resposta e com o boleto emitido; repetir com a mesma chave devolve a cobrança de antes com 200 em vez de emitir outra. Não existe cancelar por API — cobrança que já chegou no cliente se resolve na tela, com o histórico na frente.

Webhooks

A DRAP avisa você, em vez de você perguntar.

GET/webhooksLista as assinaturas
POST/webhooksAssina (devolve o secret uma vez)
DELETE/webhooks/{id}Remove a assinatura

A URL precisa ser HTTPS e pública — endereço interno (loopback, IP privado, metadata da cloud) é recusado. Máximo de 10 assinaturas por empresa. Exige o módulo Integrações ativo.

O secret aparece uma única vez, na resposta da criação. É com ele que seu receptor confere o X-DRAP-Signature de cada entrega — sem guardar, não dá pra distinguir um POST nosso de um POST de quem descobriu a URL.

Resumo

Os totais prontos, sem baixar lançamento por lançamento.

GET/resumoRealizado, em aberto, vencido e 30 dias

Filtros em GET: data_de, data_ate, centro_custo. Usa o escopo lancamentos:read — é soma do mesmo dado.

Os números seguem as mesmas definições das telas do app: transferência entre contas não vira receita nem despesa, juros e desconto entram no realizado, e proximos_30_dias não repete o que já está em vencido. Acima de 20 mil lançamentos no recorte a resposta traz truncado: true em vez de um total menor com cara de certo.

Errors

Códigos HTTP

200 — Sucesso (GET, PATCH)
201 — Criado (POST)
400 — Body inválido (detalhe Zod no detail)
401 — Key ausente, inválida ou revogada
403 — Scope insuficiente
404 — Recurso não existe nesse tenant
409 — Conflito (ex: nome duplicado)
429 — Rate-limit (vê Retry-After)
500 — Erro interno

Outbound

Webhooks.

Em vez de fazer polling pra detectar mudança, registre uma URL e a DRAP avisa quando algo acontece. Cada POST vem assinado com HMAC pra você ter certeza que veio mesmo da gente.

Eventos disponíveis

lancamento.createdLançamento criado
lancamento.updatedLançamento editado
lancamento.deletedLançamento excluído
lancamento.paidLançamento marcado como pago
lancamento.unpaidPagamento revertido
parceiro.createdParceiro criado
parceiro.updatedParceiro editado
parceiro.deletedParceiro excluído
categoria.createdCategoria criada
categoria.updatedCategoria editada
categoria.deletedCategoria excluída
conta_bancaria.createdConta bancária criada
conta_bancaria.updatedConta bancária editada
conta_bancaria.deletedConta bancária excluída
nfse.emitidaNFS-e emitida
nfse.canceladaNFS-e cancelada
cobranca.criadaCobrança criada
cobranca.pagaCobrança paga
cobranca.canceladaCobrança cancelada
orcamento.criadoOrçamento criado
orcamento.atualizadoOrçamento atualizado
anexo.adicionadoAnexo adicionado

Pra configurar, vá em Configurações → Integrações → Webhooks. Crie a subscription, escolha eventos e copie o secret (mostrado uma única vez).

Payload de exemplo

POST https://seu-endpoint.com/drap
X-DRAP-Timestamp: 1750564800
X-DRAP-Signature: sha256=4ab2…
Content-Type: application/json

{
  "event": "lancamento.created",
  "timestamp": 1750564800,
  "data": {
    "lancamento": {
      "id": "uuid",
      "data": "2026-06-22",
      "descricao": "Venda site",
      "tipo": "receita",
      "valor": 1500.00,
      "status": "pago",
      ...
    }
  }
}

Validando a assinatura (Node)

import { createHmac } from 'node:crypto';

function verificar(req, secret) {
  const ts = req.headers['x-drap-timestamp'];
  const sig = req.headers['x-drap-signature']; // sha256=...
  const body = req.rawBody; // string crua do POST
  const esperado = 'sha256=' + createHmac('sha256', secret)
    .update(`${ts}.${body}`).digest('hex');
  return esperado === sig
    && Math.abs(Date.now()/1000 - Number(ts)) < 300;
}

Política de retry

Primeira tentativa é imediata após o evento. Falhas (HTTP ≥ 400, timeout, DNS) ficam pendentes e são reentregues pelo nosso job diário com backoff: 1 min → 5 min → 30 min → 2 h. Após 4 tentativas, a delivery é marcada como dead e seu endpoint precisa estar saudável pro próximo evento. Histórico fica registrado em webhook_deliveries pra debug.

Zapier · Make · n8n

Sem app nativo.
Sem ceremony.

A combinação webhook (entrada) + REST (ação) cobre 100% dos cenários típicos no Zapier sem precisar de app oficial. Funciona igualzinho em Make e n8n.

Trigger: receber evento da DRAP

1. No Zap, escolha Webhooks by Zapier → Catch Hook.
2. Copie a URL gerada pelo Zapier.
3. Na DRAP, crie um webhook com essa URL e o(s) evento(s) que importam.
4. Clique Testar no card — Zapier pega o payload de exemplo e mostra os campos disponíveis.

Action: criar/atualizar na DRAP

1. Adicione step Webhooks by Zapier → Custom Request.
2. URL: https://empresa.drap.app.br/api/v1/lancamentos
3. Method: POST
4. Header: Authorization: Bearer drap_live_…
5. Body (JSON) com os campos do lançamento. Mapeie variáveis do trigger.

Pronto pra ligar
tudo na DRAP?

Crie sua API key em 30 segundos. Sem cartão pra testar.

Criar conta grátis Ver planos

API & Webhooks.