Saltar al contenido principal

API Partners (B2B2B)

Esta documentación describe los endpoints disponibles para los Partners de Emizor FEL bajo el prefijo unificado /api/partner/v1. Está orientada a facilitar la integración automatizada desde ERPs o plataformas de terceros (como EMIZOR 5) hacia el motor de facturación de Emizor.

Concepto y Flujo General (Impersonation)​

El modelo Multi-Tenant B2B2B permite a los "Partners" (ej. Proveedores de ERPs o Software) actuar como intermediarios para múltiples "Sub-Compañías" (sus clientes finales).

El flujo general recomendado de integración se compone de los siguientes pasos:

  1. Obtener Token Maestro (vía Panel Web)

    • Explicación: El Partner no utiliza un endpoint de login por API. Debe iniciar sesión en el panel web administrativo de Emizor, dirigirse a la sección de API Tokens y generar un Personal Access Token. Este token actúa como "Token Maestro" con permisos sobre todas sus sub-cuentas.

  2. Configurar Webhooks Globales (Recomendado)

    • Explicación: Permite registrar URLs de callback receptoras a nivel Partner (POST /api/partner/v1/webhooks). Es fundamental para recibir notificaciones de eventos asíncronos en tiempo real (ej. finalización de paramétricas update_parametrics o cambios de estado fiscal invoice_status).

  3. Crear Compañías (Onboarding)

    • Explicación: Da de alta de manera automatizada a los clientes finales (NIT, Razón Social y sectores autorizados) usando POST /api/partner/v1/companies. Retorna la clave única de arrendatario (tenant_id / company_key) necesaria para contextualizar operaciones futuras.

  4. Credenciales y Configuración SIN

    • Explicación: Carga del certificado digital p12 o token delegado SIAT (POST /credentials), logo gráfico (POST /logo), solicitud del código CUIS (POST /begin-operations) y asignación de plantillas de diseño PDF a la sucursal (PUT /templates).

  5. Emisión de Facturas (Tenant Impersonation)

    • Explicación: Una vez que el checklist de alta confirme que la empresa está lista (GET /onboarding-status -> "is_ready": true), el Partner puede consumir cualquier endpoint de la API Global de Facturación enviando siempre su Token Maestro e inyectando la cabecera tenant-key: <COMPANY_KEY>.

Diagrama Secuencial de Integración​