Crea tu primera factura
Una factura se crea con una sola petición a la API. Fiscalapi la valida, la timbra ante el SAT y te responde con el CFDI listo. Este tutorial explica qué necesitas, cómo eliges el modo de operación y qué pasa al emitir. Los modelos, las peticiones y las respuestas están en el recurso de facturas.
Antes de empezar
- Una cuenta en el ambiente de pruebas con suscripción y timbres. Consulta cómo activarlos.
- Tu tenant y una API key, que envías en los encabezados de cada petición. Consulta cómo obtenerlos.
- Un emisor con sus certificados (CSD). Para pruebas, usa una de las personas de prueba con sus certificados de prueba.
Elige el modo de operación
Fiscalapi crea facturas en dos modos de operación, con el mismo endpoint y el mismo resultado. Solo cambia cómo envías los datos:
| Modo | Qué lleva la factura | Qué necesitas antes |
|---|---|---|
| Por referencias (recomendado) | Los ID del emisor, del receptor y de los productos. | Crear tu primera persona y tu primer producto. |
| Por valores | Todos los datos del emisor, del receptor y de los conceptos, incluidos los certificados del emisor. | Nada. |
Emite la factura
Envía la factura con Crear factura ingreso por referencias o con Crear factura ingreso por valores. La factura de ingreso es la más común y se conoce simplemente como factura. Además del emisor, el receptor y los conceptos, lleva la fecha, la moneda, la forma y el método de pago y el código postal del lugar de expedición.
Puedes enviar la petición con cualquier cliente HTTP, con los SDK o con la colección de Postman, que trae ejemplos de todos los tipos de factura.
Qué pasa al emitir
- Fiscalapi valida la factura: los campos obligatorios, los catálogos y las reglas del SAT, la longitud de los textos, los decimales de los importes y la contraseña de la llave privada del emisor. Si algo falla, responde un error 400 de validación, sin timbrar ni consumir timbre.
- Fiscalapi timbra la factura ante el SAT y consume un timbre.
- Fiscalapi responde con la factura timbrada, que trae su
iden Fiscalapi, el UUID (folio fiscal) y el XML en base64.
En el ambiente de pruebas las facturas no tienen validez fiscal. Cuando tu integración esté lista, pasa a producción cambiando solo la URL y tus credenciales.
Después de emitir
Con el id de la factura puedes:
- Generar su PDF o enviarla por correo al receptor.
- Consultar su estado ante el SAT.
- Cancelarla. La cancelación termina después en el SAT, y un webhook te avisa cuando se confirma o se rechaza.
Los demás tipos de factura usan el mismo endpoint: nota de crédito, factura de pago y factura de nómina.