Documentación de la API
Acceso programático a los datos de tu LLC. URL base: https://devil.club/api/v1
Autenticación
Todas las peticiones a la API requieren una API key enviada en el header Authorization como Bearer token.
Crea y gestiona tus API keys en /api-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.
| 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
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 |
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) |
| category | string | Categoría del gasto/ingreso |
| description | string | Descripción |
| transaction_date | date | Fecha exacta (YYYY-MM-DD) |
| bank_source | string | Mercury, Stripe, Wise, manual |
| external_tx_id | string | Referencia de transacción externa |
Ledger de Gobernanza
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 |
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
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. |
Entidad (LLC)
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) |
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
Obtén tu perfil de cuenta e identificadores (pasaporte, ITIN, etc.).
Actualiza tu información de contacto (nombre, teléfono, país).
Lucy — Informes y Propuestas
Lista los informes generados por Lucy (mensuales, trimestrales, anuales). Incluye métricas, recomendaciones, alertas y decisiones propuestas.
Responde a las recomendaciones de un reporte. Puedes aprobar, rechazar, modificar o aplazar cada recomendación.
Pagos
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
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:
¿Necesitas ayuda? [email protected]