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.

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, limit, offset.

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

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.