Integracion Partner para ERP multi-tenant
Esta es la integracion para un ERP que administra varios contribuyentes. El usuario final trabaja dentro del ERP; el ERP orquesta la certificacion y la emision usando una sola credencial Partner de backend. El cliente final no necesita crear API keys, llamar a PSFE ni conocer los endpoints.
Regla de seguridad
El ERP guarda X-PARTNER-KEY exclusivamente en su backend. Nunca la envies al navegador ni la incluyas en una aplicacion movil. Las cargas de certificados usan una sesion temporal y Authorization: Upload <uploadToken>; PSFE recibe el .p12/.pfx directamente y el ERP no debe conservar el archivo ni su contraseña.
X-PARTNER-KEY: <credencial-del-erp>
Content-Type: application/json
La base del contrato es la URL HTTPS entregada durante el onboarding, seguida de /partner/v1. En el staging de referencia es https://api-psfe-staging.zarela-consulting.com/partner/v1; no codifiques el host en el ERP. El Partner identifica cada contribuyente con un externalTenantId estable del ERP; normalmente debe ser el UUID del tenant porque el webhook global lo usa para enrutar el evento. PSFE devuelve un fiscalAccountId opaco que el ERP debe conservar.
Flujo que debe implementar el ERP
La solicitud de producción no equivale a aprobación. La activación solo ocurre cuando PSFE registra la decisión interna o la evidencia DGII correspondiente. El ERP debe mostrar estados pendientes y bloquear la emisión productiva mientras production.state no sea active.
Rutas del contrato
Todas las rutas siguientes están bajo /partner/v1 y requieren X-PARTNER-KEY, salvo la carga binaria indicada.
| Etapa | Ruta | Uso |
|---|---|---|
| Provisionamiento | PUT /fiscal-accounts/by-external-id/{externalTenantId} | Crea o recupera la cuenta de un tenant. |
| Perfil | PATCH /fiscal-accounts/{id}/profile | Actualiza datos no identificadores. El RNC no se cambia aquí. |
| Estado | GET /fiscal-accounts/{id}/status | Estado consolidado de CerteCF y eCF. |
| Certificado | POST /fiscal-accounts/{id}/certificate-upload-sessions | Crea carga temporal. |
| Certificado | PUT /certificate-upload-sessions/{uploadId} | Envía el multipart con Authorization: Upload <uploadToken>. |
| Certificado | GET /fiscal-accounts/{id}/certificate | Lee metadata, nunca la clave privada. |
| Certificación | POST /fiscal-accounts/{id}/certification-cases | Vincula el caso a un set oficial habilitado. |
| Certificación | POST /fiscal-accounts/{id}/certification-cases/{caseId}/runs | Ejecuta el set oficial de CerteCF. |
| Certificación | GET /fiscal-accounts/{id}/certification-cases/{caseId} | Consulta checklist y siguiente acción. |
| Certificación | GET .../certification-cases/{caseId}/runs | Recupera runs recientes si se perdió una respuesta. |
| Certificación | GET .../runs/{runId} | Consulta el resultado del run. |
| Evidencia | GET .../runs/{runId}/evidence | Obtiene el ZIP de evidencia en base64 cuando está listo. |
| Atestaciones | POST .../attestations | Registra acciones humanas del integrador. |
| Producción | POST /fiscal-accounts/{id}/production-activation-requests | Solicita activación; no aprueba. |
| Producción | GET /fiscal-accounts/{id}/production | Consulta autorización real. |
| Emisión | POST /fiscal-accounts/{id}/production/documents?validate=true | Preflight sin efectos fiscales. |
| Emisión | POST /fiscal-accounts/{id}/production/documents | Convierte, firma y encola el e-CF. |
| Conciliación | POST .../production/documents/status/batch | Reconciliación periódica de estados. |
| Conciliación | GET .../production/documents/{documentId} | Consulta puntual de un documento. |
| Webhooks | GET/POST /webhook-endpoints | Configura eventos del ERP. |
| Webhooks | POST /webhook-endpoints/{endpointId}/test | Encola una entrega webhook.test firmada para validar recepción. |
Para validar recepción, llama POST /webhook-endpoints/{endpointId}/test con el fiscalAccountId del tenant y, opcionalmente, environment (certecf por defecto). PSFE encola una entrega webhook.test durable y la procesa el worker; no crea un documento ni envía nada a DGII. El payload conserva stateVersion: 1, externalTenantId, fiscalAccountId y environment para que el ERP pruebe su deduplicación y enrutamiento.
Emisión e idempotencia
El ERP asigna el eNCF antes de enviar el JSON y conserva esa secuencia en su POS. No se requiere que el integrador genere un Idempotency-Key para la emisión normal: PSFE deduplica por tenant, ambiente y eNCF, y rechaza una reutilización con contenido fiscal distinto. Los reintentos deben enviar el mismo JSON y el mismo eNCF.
validate=true permite detectar errores de estructura/XSD sin registrar una emisión ni enviar a DGII. La emisión normal es asíncrona: guarda documentId, encf y correlationId, acepta el webhook y reconcilia con status/batch.
Los runs de certificación sí requieren Idempotency-Key. Conserva una clave estable por intento lógico: repetir la misma clave y parámetros devuelve el mismo runId; reutilizarla con parámetros distintos devuelve 409 IDEMPOTENCY_CONFLICT. Si la respuesta se pierde, consulta la lista de runs antes de crear otro.
Webhooks Partner
Configura el endpoint con POST /webhook-endpoints. El secreto se muestra una sola vez al crear o rotar. Para verificar cada solicitud, calcula HMAC-SHA256 sobre:
{timestamp}.{rawBody}
Usa Zarela-Signature: t=<unix>,v1=<hex> y compara en tiempo constante. Persiste Zarela-Event-Id con una restricción única antes de aplicar el evento. El payload Partner incluye schemaVersion, externalTenantId, fiscalAccountId, environment, stateVersion y resource; usa stateVersion para ignorar eventos atrasados.
Cada reintento lleva un timestamp y una firma nuevos, pero conserva el mismo Zarela-Event-Id y cuerpo. Por eso debes deduplicar por event ID y validar la firma de cada intento, no guardar una firma anterior.
Eventos principales: fiscal_account.state_changed, certificate.validated, certification.state_changed, certification.run_completed, certification.action_required, production.state_changed, document.state_changed y document.action_required.
Ambientes
El flujo Partner usa CerteCF para certificación y eCF para producción. TesteCF es solo una superficie de pruebas técnicas del producto; no sustituye el caso oficial de certificación ni habilita producción. El ERP debe mostrar el ambiente al usuario, pero no mezclar certificados, estados ni secuencias entre ambientes.
Errores que el ERP debe manejar
401/403: credencial Partner ausente o scope insuficiente; no reintentar automáticamente.404 FISCAL_ACCOUNT_NOT_FOUND: provisiona primero o corrige el identificador.409 CERTIFICATION_*_NOT_READY: muestra la acción pendiente y espera el webhook.409 CERTIFICATION_EVIDENCE_NOT_READY: vuelve a consultar más tarde.423 PRODUCTION_NOT_ACTIVE: no intentes emitir; esperaproduction.state_changedconactive.429 PLAN_LIMIT_EXCEEDED: el tenant agotó la cuota que PSFE asignó al Partner; no cambies el plan desde el ERP y contacta al proveedor.- Otros
429: reintenta con backoff respetandoRetry-After.
Descarga el contrato OpenAPI público para generar tipos o clientes; consulta también la guía de webhooks.