Documentación de la API

Acceso programático a los datos de tu LLC. URL base: https://devil.club/api/v1

La API requiere al menos una LLC con suscripción Manager activa. Sin Manager, los endpoints no devolverán datos.

Quick start

En menos de un minuto: crea una key, haz tu primera llamada y verifica que recibes tu entidad.

Crea una key en /developers/keys con scope read:entity.
Guarda la key inmediatamente — solo se muestra una vez.
Lanza la petición de ejemplo (abajo) sustituyendo TU_KEY.

# Tu primera llamada — lista tus LLCs
curl -H "Authorization: Bearer dc_live_TU_KEY" \
     https://devil.club/api/v1/entity

// Ejemplo Node.js / browser (fetch nativo)
const res = await fetch("https://devil.club/api/v1/entity", {
  headers: { Authorization: "Bearer dc_live_TU_KEY" },
});
const data = await res.json();
console.log(data.data); // Array de tus entidades

Autenticación

Todas las peticiones a la API requieren una API key enviada en el header Authorization como Bearer token.

# Cada petición debe incluir este header
Authorization: Bearer dc_live_a1b2c3d4e5f6...

# Ejemplo con curl
curl -H "Authorization: Bearer dc_live_TU_KEY" \
     https://devil.club/api/v1/entity
        

Crea y gestiona tus API keys en /developers/keys. Cada key tiene scopes específicos que controlan a qué puede acceder.

Límite de peticiones

Por defecto: 100 peticiones por hora por API key. Si se excede, recibirás una respuesta 429 con un header Retry-After.

IP Whitelisting

Opcionalmente puedes restringir tu API key a direcciones IP específicas. Si está configurado, las peticiones desde otras IPs recibirán una respuesta 403 que incluye tu IP actual.

Scopes de Permisos

Selecciona solo los scopes necesarios para cada clave. Principio de mínimo privilegio.

Scopes disponibles y el área de la API a la que aplican
Scope	Acceso	Sección
read:bookkeeping	Lectura	Bookkeeping
write:bookkeeping	Escritura	Bookkeeping
read:ledger	Lectura	Ledger de Gobernanza
write:ledger	Escritura	Ledger de Gobernanza
read:documents	Lectura	Documentos
read:entity	Lectura	Entidad (LLC)
write:entity	Escritura	Entidad (LLC)
read:profile	Lectura	Perfil
write:profile	Escritura	Perfil
read:reports	Lectura	Lucy — Informes
write:reports	Escritura	Lucy — Informes
read:payments	Lectura	Pagos
read:presence	Lectura	Presencia Fiscal

Bookkeeping

GET /v1/bookkeeping read:bookkeeping

Lista las entradas de bookkeeping de una entidad. Incluye ingresos, gastos y totales resumidos.

Parámetro	Tipo	Descripción
entity_id obligatorio	integer	ID de la entidad LLC
year	integer	Filtrar por año
month	integer	Filtrar por mes (1-12)
category	string	Filtrar por categoría
limit	integer	Máx. resultados (por defecto 100, máx. 500)
offset	integer	Offset de paginación

# Obtener bookkeeping de 2026 para la entidad 42
curl -H "Authorization: Bearer dc_live_..." \
  "https://devil.club/api/v1/bookkeeping?entity_id=42&year=2026"

# Respuesta
{
  "data": [
    { "id": 1, "year": 2026, "month": 3, "category": "SaaS Revenue",
      "income": 5000.00, "expense": 0, "bank_source": "Mercury", ... }
  ],
  "summary": { "total_income": 45000, "total_expenses": 12000, "net": 33000 },
  "pagination": { "total": 87, "limit": 100, "offset": 0 }
}
            

POST /v1/bookkeeping write:bookkeeping

Añade una nueva entrada de bookkeeping. Las entradas añadidas vía API se etiquetan con source: "api".

Campo	Tipo	Descripción
entity_id obligatorio	integer	ID de la entidad LLC
year obligatorio	integer	Año
month obligatorio	integer	Mes (1-12)
income	number	Importe de ingreso (por defecto 0)
expense	number	Importe de gasto (por defecto 0)
movement_type	enum	Tipo de movimiento canónico (ver tabla abajo). Si no se envía, se infiere del signo income/expense.
category	enum	Una de las 28 categorías canónicas (ver tabla abajo). Valores legacy se mapean automáticamente.
counterparty_id	integer	Recomendado. FK a `dc.counterparties`. La “regla de oro”: quién está al otro lado del movimiento. Sin esto, Form 5472 prefill no detecta related-parties.
economic_purpose	string	Recomendado. Propósito económico (ej: “Servicios SEO mayo 2026”). Pieza 2 de la regla de oro.
document_id	integer	Recomendado. FK a `dc.documents` con el justificante (factura, contrato, recibo). Pieza 3 de la regla de oro.
description	string	Descripción libre adicional
transaction_date	date	Fecha exacta (YYYY-MM-DD)
bank_source	string	Mercury, Stripe, Wise, manual
external_tx_id	string	Referencia de transacción externa

# Ejemplo POST con las 3 piezas de la regla de oro
curl -X POST -H "Authorization: Bearer dc_live_..." \
  -H "Content-Type: application/json" \
  "https://devil.club/api/v1/bookkeeping" \
  -d '{
    "entity_id": 42,
    "year": 2026,
    "month": 5,
    "movement_type": "gasto",
    "category": "profesional_legal",
    "counterparty_id": 12,
    "economic_purpose": "Honorarios legales — revisión contrato Q2",
    "document_id": 99,
    "expense": 1240.00,
    "transaction_date": "2026-05-12"
  }'
            

⚠️ Aviso: sin counterparty_id + economic_purpose + document_id, la entrada se crea pero no cuenta como sustancia económica. El prefill automático de Form 5472 (related-party transactions) y el dossier de defensa fiscal ignoran filas sin estas 3 piezas. Es silencioso pero crítico para tax filing.

ENUMS Set canónico bookkeeping

Valores canónicos español snake_case. Cualquier valor legacy (UPPER EN o Title Case) se mapea automáticamente vía dc.category_canonical_map y dc.movement_type_canonical_map. Para integraciones nuevas, envía directamente los valores canónicos.

`movement_type` — 7 valores

Valor	Significado
ingreso	Inflow operativo (P&L)
gasto	Outflow operativo (P&L)
distribucion	Distribución a socio (Form 1120 Sch K)
aportacion	Aportación de capital del socio
transferencia_interna	Transferencia entre cuentas propias
transferencia_externa	Transferencia a cuenta externa (no operacional)
ajuste	Ajuste manual contable

`category` — 28 valores

Agrupadas por group_label para tax filing prefill:

Grupo	Categorías
INGRESOS	`venta_servicio`, `bonificacion_referido`, `interes_ganado`, `ingreso_otro`
GASTOS_DEDUCIBLES	`pago_proveedor`, `software`, `hardware`, `marketing`, `hosting`, `profesional_legal`, `gestoria_llc`, `bancario`, `viaje`, `seguro`, `gasto_apertura`, `gasto_cierre`, `impuesto_irs`, `impuesto_estatal`, `gasto_otro`
CAPITAL_FLOWS	`distribucion`, `aportacion`, `prestamo_owner`, `prestamo_terceros`, `reembolso`
TRANSFERENCIAS	`transferencia_interna`, `transferencia_externa`
NO_DEDUCIBLES	`multa_penalty` (IRS § 162(f))
OTROS	`otro`

`relation_subtype` en `dc.counterparties` — 5 valores (Form 5472 Part III)

Valor	Cuándo
self	El owner es la contraparte (cuenta personal del socio)
self_ruc	Autónomo / sole-trader del owner (mismo NIF)
spouse	Cónyuge del owner
family_other	Otros familiares (padres, hijos, hermanos)
sibling_entity	Otra entidad jurídica del owner (LLC US, SL ES, EAS, etc.)

Cuando una dc.counterparties.kind es OWNER o RELATED_ENTITY, un trigger DB-side garantiza automáticamente is_related_party = TRUE. No hace falta enviar el flag en la integración.

Ledger de Gobernanza

GET /v1/ledger read:ledger

Lista las transacciones de gobernanza/gestión. Incluye estado de decisiones, decisiones estratégicas y resoluciones del manager.

Parámetro	Tipo	Descripción
entity_id	integer	ID de la entidad LLC (obligatorio si no se indica transaction_id)
transaction_id	string	Transacción específica (ej: FGSL-2026-00042)
status	string	Filtrar: PENDING, RATIFIED, VETOED, REJECTED

POST /v1/ledger write:ledger

Envía una nueva solicitud de transacción para revisión del Manager. Crea una entrada PENDING en el ledger de gobernanza.

Campo	Tipo	Descripción
entity_id obligatorio	integer	ID de la entidad LLC
amount obligatorio	number	Importe de la transacción
category obligatorio	string	OPEX, CAPITAL_CONTRIBUTION, OWNER_DISTRIBUTION, etc.
description	string	Motivo de la transacción
strategic_decision	string	Justificación estratégica
bank	string	Banco desde el que ejecutar
exec_date	date	Fecha de ejecución solicitada
recurring	string	no, monthly, quarterly, annual

Documentos

GET /v1/documents read:documents

Lista los documentos de una entidad. Incluye articles, EIN letters, actas, tax filings y más. Cada documento incluye hash SHA-256 y estado de verificación OpenTimestamps.

Parámetro	Tipo	Descripción
entity_id	integer	ID de la entidad LLC (obligatorio si no se indica id)
id	integer	ID de documento específico
doc_type	string	Filtrar: ARTICLES, EIN_LETTER, ACTA, 8822-B, etc.

GET /v1/documents/{id}/download read:documents

Descarga un documento propio usando la misma API key; no requiere sesión web ni token de navegador.

Entidad (LLC)

GET /v1/entity read:entity

Lista tus LLCs u obtén información detallada (servicios, tax filings, titularidad).

Parámetro	Tipo	Descripción
id	integer	ID de entidad específica (omitir para listar todas)

PUT /v1/entity write:entity

Actualiza información de contacto/formación de la entidad.

Campo	Tipo	Descripción
id obligatorio	integer	ID de la entidad
founder_name	string	Nombre del fundador/organizador
founder_address	string	Dirección del fundador
founder_country	string	País del fundador
naics	string	Código NAICS del negocio

Perfil

GET /v1/profile read:profile

Obtén tu perfil de cuenta e identificadores (pasaporte, ITIN, etc.).

PUT /v1/profile write:profile

Actualiza tu información de contacto (nombre, teléfono, país).

Lucy — Informes y Propuestas

GET /v1/reports read:reports

Lista los informes generados por Lucy (mensuales, trimestrales, anuales). Incluye métricas, recomendaciones, alertas y decisiones propuestas.

POST /v1/reports write:reports

Responde a las recomendaciones de un reporte. Puedes aprobar, rechazar, modificar o aplazar cada recomendación.

# Aprobar recomendación #0, rechazar #1
curl -X POST -H "Authorization: Bearer dc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "report_id": 15,
    "decisions": [
      {"recommendation_idx": 0, "decision": "APPROVED", "client_notes": "Adelante"},
      {"recommendation_idx": 1, "decision": "REJECTED", "client_notes": "Ahora no"}
    ]
  }' \
  https://devil.club/api/v1/reports
            

Pagos

GET /v1/payments read:payments

Consulta tu historial de pagos. Incluye detalles del servicio, importes y estado.

Parámetro	Tipo	Descripción
entity_id	integer	Filtrar por entidad
year	integer	Filtrar por año

Presencia Fiscal

GET /v1/presence read:presence

Consulta el registro de presencia fiscal geo-trazada. Devuelve días acumulados por país (con gap-fill automático), alertas de umbral 183 días y, opcionalmente, el calendario día a día.

Parámetro	Tipo	Descripción
entity_id	integer	Requerido. ID de la entidad
year	integer	Año fiscal (por defecto: año actual)
detail	boolean	Si `true`, incluye el mapa día a día en `calendar`

Respuesta incluye summary (países + días), warnings (niveles: info / warning / danger / exceeded) y opcionalmente calendar (mapa YYYY-MM-DD → país).

Manejo de errores

Todos los errores siguen un formato consistente:

{ "error": "Descripción de lo que falló" }

Tabla de códigos HTTP emitidos por la API
Código	Significado
400	Petición incorrecta — parámetros faltantes o inválidos
401	No autorizado — API key inválida o no proporcionada
403	Prohibido — IP no autorizada, scope insuficiente o sin titularidad
404	No encontrado — el recurso no existe o no te pertenece
429	Límite excedido — demasiadas peticiones, consulta el header Retry-After
500	Error del servidor — contacta con soporte

Changelog

Cambios no destructivos se añaden sin preaviso. Cualquier cambio breaking se anuncia con mínimo 30 días de antelación al email de la cuenta y se publica aquí.

Historial de versiones públicas
Fecha	Cambio
2026-04-18	Añadido Quick start, pestañas curl/JS y copia-al-portapapeles en ejemplos.
2026-04	Endpoint `GET /v1/presence`: presencia fiscal geo-trazada con avisos 183 días.
2026-03	Endpoint `GET /v1/documents/{id}/download`: descarga directa con la misma API key.
2026-02	Scopes `read:reports` / `write:reports`: respuesta a recomendaciones de Lucy.
2026-01	Lanzamiento público v1: bookkeeping, ledger, documents, entity, profile, payments.

¿Necesitas ayuda? [email protected]