Introducción
Qué ofrece hoy la API de Trifaco, en qué ambientes funciona y cómo leer esta documentación.
Trifaco expone por API la facturación electrónica colombiana: prevalidar, emitir y consultar facturas y notas, descargar sus archivos, entregarlos al comprador y recibir avisos en tu sistema.
Estado del contrato
El contrato es la versión 0.1.0-draft. Solo una parte de las operaciones del contrato está conectada, y producción está deshabilitada. La referencia de este sitio publica únicamente las operaciones conectadas.
Ambientes
| Ambiente | Para qué sirve | Contacta a la DIAN |
|---|---|---|
simulation | Integrar y probar tu código con resultados ficticios (SIMULATION_ONLY). | No |
qualification | Habilitación: set de pruebas de la DIAN con certificado, firma y configuración reales. | Sí, ambiente de pruebas |
production | Emisión con validez fiscal. | Deshabilitado: las credenciales responden 403 ENVIRONMENT_DISABLED |
La credencial (X-API-Key) fija empresa, ambiente y actor. No existe un encabezado para cambiar de ambiente: una clave de simulación nunca se convierte en una de habilitación. Detalle en Simulación y producción.
Cómo está organizada
Recorrido rápido
Levanta el servicio en tu equipo, emite una factura simulada, recibe el webhook y descarga sus archivos.
Autenticación y permisos
Credenciales, roles, permisos mínimos, rotación y aislamiento entre empresas.
Errores e idempotencia
Cómo reintentar sin duplicar documentos y qué hacer con cada código.
Webhooks
Configurar destinos, verificar la firma, deduplicar y reproducir eventos.
Referencia de la API
La referencia se genera a partir de api/openapi.yaml y del inventario de operaciones. Cada operación indica su estado (implementada o parcial), sus ambientes, los permisos efectivos y su alcance. Las operaciones pendientes no aparecen: si llamas una ruta pendiente, la API responde 422 UNSUPPORTED_OPERATION.
Otras fuentes del repositorio:
- Matriz fiscal: casos fiscales soportados y restricciones.
- Política de compatibilidad: cómo evoluciona el contrato mientras sea draft.
- Ejemplos JSON: cuerpos sintéticos validados contra el esquema.
Convenciones
- Los ejemplos usan datos ficticios y el origen local
http://127.0.0.1:3000. Fuera de tu equipo, usa HTTPS y el origen que te entregue Trifaco. El dominioapi.trifaco.exampledel contrato es ilustrativo. - Las mutaciones exigen
Idempotency-Key. Conserva el cuerpo y la clave antes del primer envío (ver Errores e idempotencia). - Tolera propiedades, estados y códigos nuevos sin inferir éxito ni volver a emitir.