1. Prepara el cliente y su establecimiento
Identifica al contribuyente que emitirá los documentos y el establecimiento correspondiente a cada venta. Antes de consumir operaciones FEL, registra el cliente, valida su acceso FEL y confirma que dispone de un plan vigente con solicitudes disponibles.
Usa los establecimientos asociados a ese cliente. Si administras varios contribuyentes, conserva en tu sistema la relación entre cada venta, cliente y establecimiento; no intercambies sus credenciales.
El tutorial para crear un cliente muestra la preparación desde el portal. Para altas desde tu aplicación, consulta el contrato de onboarding de integradores.
2. Distingue Bearer y token_fel
- Bearer token: autentica al usuario de la plataforma mediante el encabezado
Authorization. - token_fel: identifica las credenciales FEL cifradas del cliente y se envía en el cuerpo JSON según el contrato de la operación.
Los tokens creados en el portal no tienen vencimiento automático y pueden revocarse. Los obtenidos mediante POST /api/login duran 24 horas. Consulta el contrato de autenticación y vigencia de tokens para preparar su renovación.
Realiza las llamadas desde el servidor de tu ERP, POS o aplicación sobre HTTPS. Conserva los tokens en almacenamiento seguro; no los incluyas en el código del navegador, URLs, repositorios ni logs.
3. Emite desde el flujo de venta de tu ERP o POS
Cuando la venta esté lista para facturarse, prepara los datos del receptor, establecimiento e ítems para POST /api/agencia-virtual/emitir-factura. Envía la identificación del receptor como NIT o CUI según corresponda, junto con los campos requeridos por el contrato vigente.
Consulta los campos y ejemplos de emisión de factura antes de construir la petición. Para una factura cambiaria u otro documento, usa la operación específica documentada.
Relaciona el número de autorización devuelto con la venta original. Confirma la emisión con la respuesta y los documentos correspondientes antes de marcarla como facturada en tu sistema.
4. Conserva y recupera XML y PDF
Almacena la autorización y los archivos recibidos con la venta a la que pertenecen. El contrato de emisión contempla PDF opcional mediante descargar_pdf; revisa su valor predeterminado y la forma de respuesta antes de procesarlo.
Si necesitas recuperar los archivos posteriormente, usa las operaciones de descarga de XML, descarga de PDF y consulta de documentos.
Para repasar la diferencia entre autorización, XML y PDF, consulta qué es FEL y cómo se representa un DTE.
5. Resuelve un timeout antes de reintentar
Un corte de red o un HTTP 504 puede ocurrir después de que la SAT haya procesado el documento. Una respuesta perdida no demuestra que la emisión o anulación falló.
- Conserva la venta, el contexto de la operación y el
X-Correlation-IDcuando esté disponible. - Consulta el DTE y verifica emisor, receptor, monto, fecha y estado antes de relacionar un resultado recuperado.
- Recupera el documento existente cuando corresponda. Considera una nueva emisión solo después de resolver el resultado de la operación anterior.
Para los POST de onboarding que requieren Idempotency-Key, conserva la misma clave y el mismo payload al recuperar una operación. Esa cabecera pertenece a los contratos que la documentan; no sustituye la consulta del resultado de una emisión FEL.
Revisa el manejo de errores y reintentos antes de automatizar estos casos.
Antes de activar tu integración
API FelCore es una plataforma privada e independiente de la SAT. No dispone de un ambiente aislado de pruebas: las operaciones de emisión y anulación pueden afectar DTE reales. Revisa los contratos y prepara validaciones locales antes de realizar operaciones fiscales autorizadas.
En la documentación técnica y quickstart encontrarás los ejemplos y la colección Postman. Si usas WordPress, consulta el plugin para WooCommerce.