Ambientes y pruebas
La llave y la URL base deben corresponder al mismo ambiente.
| Ambiente | Prefijo de llave | Timbrado |
|---|---|---|
| Pruebas | fc_test_... |
No tiene validez fiscal ni genera cargos por timbres |
| Producción | fc_live_... |
Emite CFDI y genera consumo facturable |
La base de pruebas es https://sandbox.factucat.com/api/v1. La base de producción es https://factucat.com/api/v1.
Qué trae sandbox
Sección titulada «Qué trae sandbox»El ambiente público de pruebas está pensado para integrar sin fricción:
- Registro en sandbox.factucat.com y llaves con prefijo
fc_test_.... - Sin tarjeta para las primeras solicitudes ni para el timbrado de prueba: el acceso a la API no exige plan de pago en este ambiente.
- CSD de prueba compartido del SAT EKU9003173C9, precargado cuando la cuenta aún no tiene CSD. Los datos fiscales asociados son de solo lectura; no subas tu CSD real aquí.
- Comportamiento de sandbox activado en el servidor (
FACTUCAT_API_SANDBOX): habilita el acceso sin plan de pago, el CSD de prueba y reglas de timbrado acordes al ambiente de pruebas. No uses ese flag en tu integración cliente: basta con la URL y la llavefc_test_....
Los comprobantes emitidos en sandbox no tienen validez fiscal y no generan cargos por timbres.
Empieza en sandbox
Sección titulada «Empieza en sandbox»Entra a sandbox.factucat.com, abre tu cuenta de pruebas y genera una llave fc_test_... en Configuración → API keys.
Guarda la llave en FACTUCAT_API_KEY. Para los ejemplos HTTP de estas guías, configura también la URL base:
export FACTUCAT_API_URL='https://sandbox.factucat.com/api/v1'La consulta GET /me comprueba la conexión y los permisos. Puedes seguir Cómo timbrar un CFDI completo en este ambiente para probar tu integración.
Configura tu integración
Sección titulada «Configura tu integración»Mantén la URL base y la llave como configuración de tu servidor. Para cambiar de ambiente, sustituye ambas. Cada ambiente tiene su propia cuenta, configuración y llaves; renombrar el prefijo de una llave no la convierte en una llave del otro ambiente.
En el SDK puedes omitir baseUrl: una llave fc_test_... selecciona sandbox y las demás seleccionan producción. Si proporcionas baseUrl, esa URL tiene prioridad.
Los ID de clientes, borradores y facturas también pertenecen al ambiente donde se crearon. Utiliza registros separados en tu sistema para evitar mezclarlos.
Pasa a producción
Sección titulada «Pasa a producción»Prepara tu cuenta emisora en FactuCat con tu RFC, CSD vigente y un plan con acceso a la API. Genera una llave fc_live_... y cambia la URL de los ejemplos HTTP a https://factucat.com/api/v1. Con el SDK, basta con cambiar la llave si omites baseUrl.
No envíes una llave fc_test_... a producción: la solicitud será rechazada. Crea o consulta los clientes y documentos del ambiente de producción; los IDs del sandbox no se trasladan. El timbrado en producción emite comprobantes con validez fiscal y genera consumo facturable.