Referencia
Referencia de endpoints
Todos los endpoints públicos con su método, scope y descripción, en una sola tabla.
Prefijo común, salvo donde se indique lo contrario:
https://facty.mx/api/authenticated/{orgSlug}
Header en todas: X-API-Key: fk_…
Conexión y capacidades
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /context | membresía | Identidad de la organización, permisos de la llave, perfil fiscal, estado del CSD, series, complementos disponibles y stampingMode. Llámalo al configurar. |
Clientes
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /clients | clients.read | Listar y buscar (q, limit ≤500, cursor). |
POST | /clients | clients.create | Alta. Admite upsert. |
GET | /clients/{clientId} | clients.read | Detalle. |
PATCH | /clients/{clientId} | clients.update | Actualización parcial. |
GET | /clients/{clientId}/ppd-invoices | invoices.read | Facturas PPD con saldo pendiente de ese cliente. |
Productos
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /products | products.read | Listar y buscar (q, limit ≤500, cursor). |
POST | /products | products.create | Alta. Admite upsert con tu code. |
GET | /products/{productId} | products.read | Detalle. |
PATCH | /products/{productId} | products.update | Actualización parcial. |
Facturas y CFDI
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
POST | /invoices | invoices.create | Timbrar. type: ingreso, egreso, traslado, nomina. |
GET | /invoices | invoices.read | Listar. Filtros: status, type, clientId, uuid, idempotencyKey, dateFrom, dateTo, limit ≤100, cursor. |
GET | /invoices/{invoiceId} | invoices.read | Detalle con conceptos e impuestos. |
GET | /invoices/{invoiceId}/xml | invoices.read | URL firmada del XML (5 min). |
GET | /invoices/{invoiceId}/pdf | invoices.read | URL firmada del PDF (5 min). |
GET | /invoices/{invoiceId}/cfdi | invoices.read | ZIP con XML + PDF (binario). |
GET | /invoices/{invoiceId}/acuse | invoices.read | PDF del acuse de cancelación (binario). |
GET | /invoices/{invoiceId}/balance | invoices.read | Saldo y complementos aplicados. |
GET | /invoices/{invoiceId}/sat-status | invoices.read | Estatus en el SAT. Cacheado 30 min; ?force=true consulta de verdad y gasta un folio. |
POST | /invoices/{invoiceId}/cancel | invoices.cancel | Cancelar. motivo 01–04; 01 exige folioSustitucion. |
POST | /invoices/{invoiceId}/email | invoices.send | Enviar XML + PDF por correo. |
Pagos y complementos (REP)
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
POST | /payments | payments.create | Registrar un pago y, con stamp: true, timbrar el REP. |
GET | /payments | payments.read | Listar (limit ≤100, cursor). |
GET | /payments/{paymentId} | payments.read | Detalle. |
POST | /payments/{paymentId}/stamp | payments.create | Timbrar un pago registrado con stamp: false. |
POST | /payments/{paymentId}/cancel | invoices.cancel | Cancelar el REP. Consume un timbre. |
Nómina
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /empleados | invoices.read | Listar y buscar (q, limit ≤500, cursor). |
POST | /empleados | invoices.create | Alta de empleado. |
GET | /empleados/{empleadoId} | invoices.read | Detalle. |
PATCH | /empleados/{empleadoId} | invoices.create | Actualización. |
POST | /invoices con type: "nomina" | invoices.create | Timbrar el recibo. |
Retenciones
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
POST | /retenciones | invoices.create | Timbrar un CFDI de retenciones. |
GET | /retenciones | invoices.read | Listar (status, limit ≤100, cursor). |
GET | /retenciones/{retencionId} | invoices.read | Detalle. |
POST | /retenciones/{retencionId}/cancel | invoices.cancel | Cancelar. Consume un timbre. |
Cuentas y movimientos
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /accounts | accounts.read | Cuentas bancarias y de efectivo. Filtros: kind (bank/cash), includeArchived. |
POST | /accounts | accounts.write | Alta de cuenta. |
GET | /accounts/{accountId} | accounts.read | Detalle. |
PATCH | /accounts/{accountId} | accounts.write | Actualización. |
GET | /accounts/{accountId}/movements | accounts.read | Movimientos. |
GET | /accounts/{accountId}/ledger | accounts.read | Auxiliar de la cuenta. |
POST | /transfers | transfers.create | Traspaso entre cuentas. |
Timbres y facturación
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /billing/balance | billing.read | Saldo actual de timbres. |
GET | /billing/ledger | billing.read | Historial de compras, consumos y reembolsos. |
GET | /api/authenticated/billing/packages | — | Paquetes de timbres disponibles. Sin organización en la URL. |
Reportes
| Método | Ruta | Scope | Descripción |
|---|---|---|---|
GET | /reports/summary | reports.read | Resumen agregado. |
GET | /reports/invoices.csv | reports.read | Exportación de facturas en CSV. |
GET | /reports/monthly-summary.csv | reports.read | Resumen mensual en CSV. |
Catálogos del SAT
Sin organización en la URL. Cualquier API key válida sirve.
| Método | Ruta | Descripción |
|---|---|---|
GET | /api/authenticated/catalogs/sat?type=…&q=… | Catálogo general. Ver tipos disponibles. |
GET | /api/authenticated/catalogs/clave-prod-serv?q=… | Búsqueda en c_ClaveProdServ. q de 2+ caracteres. |
GET | /api/authenticated/catalogs/clave-unidad?q=… | Búsqueda en c_ClaveUnidad. |
Límites
| Concepto | Valor |
|---|---|
| Lecturas | 600 por minuto, por llave |
| Escrituras | 60 por minuto, por llave |
limit en clientes, productos y empleados | 500 |
limit en facturas, pagos y retenciones | 100 |
| Vigencia de las URLs firmadas | 5 minutos |
| Caché del estatus SAT | 30 minutos |
Longitud de idempotencyKey | 8–128 caracteres |
Fuera de esta API
Estas rutas existen pero no aceptan API keys: la administración interna de la
plataforma y /api/authenticated/me (una llave autentica a una organización, no a
una persona). No las incluimos aquí porque no forman parte de la superficie
pública.
Para integraciones con agentes de IA, Facty también expone un servidor MCP con las mismas reglas y los mismos scopes.