DealFactoryDocs
GitHubCentro de ayudaMis API keys

Empezar

  • Introducción
  • Autenticación
  • Rate limits
  • Errores

REST API

  • Opportunities
  • Contacts
  • Accounts
  • Quotes
  • Messages

Eventos

  • Webhooks salientes
  • Catálogo de eventos

Recursos

  • SDKs oficiales
  • OpenAPI spec

REST API v1

DealFactory API Reference

REST + Webhooks + SDKs oficiales para Node.js, Python, Go y PHP. JSON over HTTPS, autenticación por bearer token, idempotencia con header dedicado.

Introducción

Quick start en 2 minutos

La API de DealFactory te permite acceder a deals, contactos, cuentas, cotizaciones, conversaciones y eventos desde tus apps. Toda la funcionalidad del frontend está disponible vía REST.

Tu primer request
curl https://api.dealfactory.app/v1/opportunities \
  -H "Authorization: Bearer df_live_8a4f...c2f1" \
  -H "Accept: application/json"

El base URL es https://api.dealfactory.app/v1. Sandbox usa https://api.sandbox.dealfactory.app/v1.

Autenticación

Bearer token en header

Todas las requests requieren un Authorization: Bearer <token> header. Las keys se generan en Configuración → Integraciones.

  • Keys de producción comienzan con df_live_
  • Keys de sandbox comienzan con df_test_
  • Cada key tiene scopes granulares (read/write × resource)
  • Las keys nunca se exponen en logs ni en URL — solo headers
Headers obligatorios
Authorization: Bearer df_live_8a4f...c2f1
Accept: application/json
Content-Type: application/json
X-Idempotency-Key: 5d8a-uuid (recomendado en POST/PUT)

Rate limits

Por API key, ventana deslizante

PlanReads / minWrites / minBurst
Pilot12030200
Growth6001201k
Enterprise3k6005k
CorporateCustomCustomCustom

Cuando excedés el límite, recibís HTTP 429 con header Retry-After en segundos.

Errores

HTTP status + JSON estructurado

Errores devuelven JSON con esta forma:

json
{
  "error": {
    "code": "validation_failed",
    "message": "El campo 'amount' es requerido",
    "field": "amount",
    "request_id": "req_8a4f9c2e1b3d"
  }
}
  • 400 — validation_failed, malformed JSON
  • 401 — missing/invalid token
  • 403 — token sin scope para esa operación
  • 404 — resource no existe
  • 409 — conflict (ej: opportunity_id duplicado)
  • 429 — rate limit hit
  • 5xx — server error · reintentar con backoff exponencial

Opportunities

Crear, listar, mover de stage, marcar won/lost

GET/v1/opportunitiesLista paginada con filtros
bash
curl 'https://api.dealfactory.app/v1/opportunities?stage=Negotiation&limit=50' \
  -H "Authorization: Bearer df_live_..."
POST/v1/opportunitiesCrear oportunidad
bash
curl -X POST 'https://api.dealfactory.app/v1/opportunities' \
  -H "Authorization: Bearer df_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stevia Pampa - Pedido marzo",
    "account_id": "acc_8a4f",
    "amount": 8500,
    "expected_close": "2026-05-15",
    "stage": "Discovery",
    "source": "meta_ad"
  }'
PATCH/v1/opportunities/{id}/stageMover de stage (con motivo opcional)
POST/v1/opportunities/{id}/wonMarcar won (registra outcome event)
POST/v1/opportunities/{id}/lostMarcar lost (requiere motivo)

Contacts

CRUD + bulk import + dedup automático

GET/v1/contactsLista paginada
POST/v1/contactsCrear contacto (con dedup por phone/email)
POST/v1/contacts/bulk_importCSV upload bulk · max 50k rows

Accounts

Empresas + buying committee + LTV

GET/v1/demo/accounts/{id}Cuenta completa con buying committee + opps activas
PATCH/v1/demo/accounts/{id}Update partial fields

Quotes

Cotizaciones con line items + public link

POST/v1/demo/quotesCrear quote desde opportunity
POST/v1/demo/quotes/{id}/sendMandar al cliente vía WA/email
GET/v1/demo/quotes/{id}/public_linkLink público con token (no auth)

Messages

WA / Email / LinkedIn outbound

POST/v1/messagesMandar mensaje (canal + template + variables)
json
{
  "channel": "whatsapp",
  "to": "+5491159999999",
  "template": "recordatorio_pago",
  "variables": { "name": "Mariana", "amount": "8500" }
}

Webhooks salientes

HMAC SHA256 verification + retry policy

Configurás un endpoint en Integraciones. DealFactory POSTea cada evento con headers de firma:

bash
POST /tu/endpoint
X-DF-Signature: sha256=8a4f9c2e1b3d...
X-DF-Event-Id: evt_8a4f9c2e
X-DF-Timestamp: 1704067200
Content-Type: application/json

{
  "event": "opportunity.won",
  "data": { ... }
}

Verificá la firma HMAC con tu webhook secret. Reintentamos 3 veces (1m, 5m, 15m) ante 5xx o timeout >10s. Pasados los 3 reintentos, el evento queda en DLQ visible en /demo/configuracion/integraciones.

Verificar firma (Node.js)
import crypto from "crypto";

function verify(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return signature === `sha256=${expected}`;
}

Catálogo de eventos

Todos los eventos que podés suscribir

opportunity.created

Nueva oportunidad creada (manual o vía AI)

opportunity.stage_changed

Cambió de stage (incluye prev/next)

opportunity.won

Marcada como ganada

opportunity.lost

Marcada como perdida (incluye motivo)

quote.sent

Quote enviada al cliente

quote.accepted

Cliente aceptó la quote

quote.rejected

Cliente rechazó la quote

sales_order.created

Pedido creado

sales_order.paid

Pedido pagado (vía MercadoPago/transferencia)

lead.qualified

Lead pasó qualification gate (BANT/MEDDIC)

conversation.handoff

Bot escala a humano (incluye motivo)

ai.action_executed

Cerebro AI ejecutó next_action

contact.created

Nuevo contacto en CRM

SDKs oficiales

Listos para producción

Node.js

bash
npm i @dealfactory/sdk

Min version: 18.0+

Python

bash
pip install dealfactory

Min version: 3.9+

Go

bash
go get github.com/dealfactory/go-sdk

Min version: 1.21+

PHP

bash
composer require dealfactory/sdk

Min version: 8.1+

OpenAPI spec

Genera tu propio cliente

Spec OpenAPI 3.1 disponible en:

bash
https://api.dealfactory.app/v1/openapi.yaml

Usá openapi-generator para generar clientes en 60+ lenguajes.

¿Listo para empezar?

Generá tu primera API key y conectá DealFactory a tu stack en minutos.

Mis API keysCentro de ayuda