Referencia de API

Esta referencia se genera del OpenAPI real de la aplicación: si un endpoint no está aquí, no existe en producción. Todos los endpoints viven bajo https://api.434alchemycode.com/v1 y usan API keys salvo donde se indica.

Descargar openapi.yaml Copia local (offline)

El archivo servido por la API en /openapi.yaml siempre está actualizado. La copia local de este sitio se genera en el mismo build de la documentación; si difieren, gana la de la API.

Convenciones

Tema	Convención
Base URL	`https://api.434alchemycode.com/v1`
Versión	`v1` en la ruta; el header `X-API-Version` confirma `v1`.
Auth	`Authorization: Bearer ck_live_...` o `ck_test_...`.
Content-Type	`application/json`; multipart sólo en la carga de e.firma.
Errores	`application/problem+json` (RFC 9457) con `code` estable.
Paginación	`page` desde 1 y `per_page` (máx. 100); respuesta con `total`, `page` y `per_page`.
Fechas	ISO 8601 en UTC (`+00:00`) salvo fechas de calendario (`YYYY-MM-DD`).
Importes	Texto decimal (`"1234.50"`) para no perder precisión.
Tags	`Plataforma`, `Empresas`, `Servicios`, `Llaves`, `Webhooks`

Plataforma

Salud, catálogo de servicios, cuenta, consumo y descarga de archivos firmados.

Método	Ruta	Resumen	Auth	Documentación
GET	`/v1/files/{file_id}`	Descarga un artefacto con URL firmada	`URL firmada`	Archivos
GET	`/v1/health`	Estado del servicio	`Pública`	Estado
GET	`/v1/me`	Cuenta autenticada, plan y cuota	`API key`	Cuota
GET	`/v1/services`	Catálogo de servicios	`Pública`	Catálogo
GET	`/v1/usage/events`	Bitácora de peticiones (paginada)	`usage:read`	Consumo
GET	`/v1/usage`	Consumo agregado de la cuenta	`usage:read`	Consumo

Empresas

Alta de empresas y credenciales cifradas (e.firma, IMSS, Infonavit).

Método	Ruta	Resumen	Auth	Documentación
POST	`/v1/companies/{company_id}/credentials/sat`	Carga e.firma (.cer, .key y contraseña)	`credentials:write`	e.firma
DELETE	`/v1/companies/{company_id}/credentials/{kind}`	Elimina credenciales (fiel \| imss \| infonavit)	`credentials:write`	Portales
POST	`/v1/companies/{company_id}/credentials/{portal}`	Carga credenciales de IMSS o Infonavit	`credentials:write`	Portales
GET	`/v1/companies/{company_id}/credentials`	Estado de credenciales de la empresa	`companies:read`	Credenciales
GET	`/v1/companies/{company_id}`	Detalle de empresa	`companies:read`	Empresas
PATCH	`/v1/companies/{company_id}`	Actualiza empresa	`companies:write`	Empresas
DELETE	`/v1/companies/{company_id}`	Archiva empresa (borrado lógico)	`companies:write`	Empresas
GET	`/v1/companies`	Lista empresas	`companies:read`	Empresas
POST	`/v1/companies`	Crea una empresa	`companies:write`	Empresas

Servicios

Ejecución de los 8 servicios y seguimiento de trabajos.

Método	Ruta	Resumen	Auth	Documentación
POST	`/v1/captcha/resoluciones`	Resuelve un CAPTCHA (síncrona)	`API key`	Servicio
POST	`/v1/imss/buzones`	Sincroniza el Buzón IMSS	`API key`	Servicio
POST	`/v1/imss/opiniones`	Opinión de Cumplimiento IMSS	`API key`	Servicio
POST	`/v1/infonavit/opiniones`	Opinión de Cumplimiento Infonavit	`API key`	Servicio
POST	`/v1/jobs/{job_id}/cancel`	Cancela un trabajo en cola	`API key`	Cancelación
GET	`/v1/jobs/{job_id}`	Consulta un trabajo	`jobs:read`	Trabajos
GET	`/v1/jobs`	Lista trabajos	`jobs:read`	Trabajos
POST	`/v1/sat/articulo-69b`	Consulta Artículo 69-B (síncrona)	`API key`	Servicio
POST	`/v1/sat/constancias`	Constancia de Situación Fiscal	`API key`	Servicio
POST	`/v1/sat/domicilios`	Estatus de domicilio fiscal	`API key`	Servicio
POST	`/v1/sat/opiniones`	Opinión de Cumplimiento SAT (32-D)	`API key`	Servicio

Llaves

Gestión de API keys y scopes.

Método	Ruta	Resumen	Auth	Documentación
DELETE	`/v1/keys/{key_id}`	Revoca una llave	`keys:write`	Rotación
GET	`/v1/keys`	Lista llaves de la cuenta	`keys:read`	Llaves
POST	`/v1/keys`	Crea una llave (se muestra una sola vez)	`keys:write`	Llaves

Webhooks

Notificaciones firmadas de trabajos terminados.

Método	Ruta	Resumen	Auth	Documentación
POST	`/v1/webhooks/{webhook_id}/test`	Envía un evento de prueba	`webhooks:write`	Prueba
DELETE	`/v1/webhooks/{webhook_id}`	Desactiva un webhook	`webhooks:write`	Webhooks
GET	`/v1/webhooks`	Lista webhooks	`webhooks:write`	Webhooks
POST	`/v1/webhooks`	Crea un webhook (secreto visible una sola vez)	`webhooks:write`	Webhooks

Consola interna

Estos endpoints sostienen la consola de AlchemyCode y la sesión del panel. No forman parte del contrato público: requieren cookie de sesión o token de staff y no están disponibles con API keys de cliente. Se listan para que el OpenAPI sea completo.

Método	Ruta	Resumen	Auth	Documentación
POST	`/v1/auth/invitations/accept`	Acepta invitación y crea la cuenta	`API key`	Interna
GET	`/v1/auth/invitations/{token}`	Valida una invitación antes de aceptarla	`API key`	Interna
POST	`/v1/auth/login`	Inicia sesión en el panel	`API key`	Interna
POST	`/v1/auth/logout`	Cierra sesión	`API key`	Interna
GET	`/v1/auth/me`	Usuario de la sesión actual	`API key`	Interna
POST	`/v1/auth/password`	Cambia la contraseña	`API key`	Interna
GET	`/v1/admin/accounts/{account_id}`	Detalle de cuenta	`API key`	Interna
PATCH	`/v1/admin/accounts/{account_id}`	Ajusta plan, cuota o estado	`API key`	Interna
GET	`/v1/admin/accounts`	Cuentas de clientes	`API key`	Interna
GET	`/v1/admin/ai`	Consumo de IA por cuenta, modelo y operación	`API key`	Interna
GET	`/v1/admin/audit`	Auditoría	`API key`	Interna
POST	`/v1/admin/invitations/{invitation_id}/revoke`	Revoca invitación	`API key`	Interna
GET	`/v1/admin/invitations`	Invitaciones	`API key`	Interna
POST	`/v1/admin/invitations`	Invita a un desarrollador	`API key`	Interna
GET	`/v1/admin/metrics`	Tablero global	`API key`	Interna
GET	`/v1/admin/services`	Catálogo con precio y unidades (editable a futuro)	`API key`	Interna
GET	`/v1/admin/usage`	Consumo global por cuenta y servicio	`API key`	Interna

Esquemas y generación de clientes

El OpenAPI incluye los esquemas de entrada (CompanyCreate, ConstanciaRequest, KeyCreateRequest, WebhookCreateRequest, etc.) y los códigos de respuesta. Puedes generar un cliente con:

Shell

# Ejemplo con openapi-generator (Java, PHP, Python, TypeScript…)
openapi-generator-cli generate \
  -i https://api.434alchemycode.com/openapi.yaml \
  -g php \
  -o ./sdk-alchemy

La documentación por servicio (campos, ejemplos y errores propios) está en las páginas de Servicios.