Cómo emitir facturas CFDI 4.0 por API desde tu sistema
28 de octubre de 2026 · Equipo Zoosial
Con la API de Zoosial emites facturas CFDI 4.0, notas de crédito y complementos de pago desde tu propio sistema: registras los datos fiscales del perfil, subes tu CSD y llamas a POST /profiles/:id/invoices. Puedes empezar en modo pruebas, gratis y sin validez fiscal; el modo real exige completar los pendientes del perfil (consulta su estado en GET /profiles/:id/invoicing). Es un producto en beta y este artículo no es asesoría fiscal: consulta a tu contador.
Cómo está organizado
Cada perfil de Zoosial factura con su propio RFC. Eso sirve igual si facturas para tu negocio o si eres un despacho con varios clientes. Puedes trabajar en pruebas y en real a la vez: con la cabecera X-Invoicing-Mode: test una llamada va a pruebas aunque el perfil ya esté en real.
Paso 1: datos fiscales y CSD
POST /profiles/:id/invoicingconlegal_name(como en tu constancia del SAT),tax_system(régimen de 3 dígitos) yzip(5 dígitos).PUT /profiles/:id/invoicing/csdcon tu certificado y llave en base64. Zoosial los reenvía al proveedor de timbrado y no los guarda.- Para el modo real, firma la Carta Manifiesto con tu e.firma y llama a
POST /profiles/:id/invoicing/live. Si falta algo, responde con la lista de pendientes.
Paso 2: emite la factura
POST /profiles/:id/invoices
{ "customer": { "legal_name": "…", "tax_id": "<RFC>", "tax_system": "…", "zip": "…" },
"items": [ { "description": "…", "quantity": 1, "price": <monto>, "product_key": "<clave SAT>" } ],
"payment_form": "<forma de pago>",
"idempotency_key": "pedido-1234" }
Antes de timbrar se validan reglas básicas, por ejemplo que el RFC sea coherente con el régimen. Si repites un idempotency_key, no se timbra otra factura. Cada concepto admite IVA, descuento y retenciones, y la respuesta trae el uuid y el estado. Descarga el archivo con GET /profiles/:id/invoices/:invId/pdf o /xml; el PDF sale con tu logo y color.
Notas de crédito y complementos de pago
- Nota de crédito:
POST /profiles/:id/invoices/:invId/credit-notecon el monto. Genera un CFDI de egreso relacionado a la factura original. - Complemento de pago: si la factura es a crédito (
payment_method: "PPD"), registra cada pago conPOST /profiles/:id/invoices/:invId/payments. La parcialidad y el saldo los calcula el proveedor de timbrado. - Cancelación:
DELETE /profiles/:id/invoices/:invId?motive=02. Los motivos van del 01 al 04 y el 01 exige indicar la factura que sustituye.
Avisos y límites
Si una factura cambia de estado fuera de tu petición, te llegan los eventos invoice.status_updated e invoice.cancellation_status_updated a tus webhooks. El tope es de 30 emisiones por minuto por perfil.
Precio
Las pruebas son gratis. En real hay un plan mensual por RFC, en MXN más IVA:
| Plan | Al mes | Facturas incluidas |
|---|---|---|
| Básico | $99 | 50 |
| Negocio | $199 | 150 |
| Pro | $399 | 400 |
Si te pasas, hay paquetes de timbres que no caducan: 100 por $100, 500 por $450 y 1,000 por $850. Detalle en Facturas CFDI 4.0.
Preguntas frecuentes
¿Puedo probar la facturación por API sin gastar timbres?
Sí. El modo pruebas es gratis y sus facturas no tienen validez fiscal. Sirve para integrar y simular antes de pasar al modo real.
¿Cómo se emite un complemento de pago por API?
Se emite sobre una factura a crédito (PPD) con POST /profiles/:id/invoices/:invId/payments, indicando el monto y la forma de pago. El proveedor de timbrado calcula la parcialidad y el saldo.
¿Zoosial guarda mi CSD?
No. Se envía al proveedor de timbrado y no se guarda en Zoosial.
¿Cómo cancelo una factura CFDI por API?
Con DELETE /profiles/:id/invoices/:invId y el parámetro motive (01 a 04). El motivo 01 exige indicar la factura que la sustituye.
Referencia completa en llms.txt. Para probar, crea una cuenta gratis.