openapi: 3.1.0
info:
  title: ZarelaFact API
  version: 0.2.0
  summary: API JSON-first para emision, certificacion y recepcion e-CF DGII.
  description: |
    Contrato inicial de la API PSFE. Las rutas privadas se sirven bajo un
    ambiente DGII: `/TesteCF`, `/CerteCF` o `/eCF`. Los endpoints publicos DGII
    se mantienen sin autenticacion interactiva porque DGII y otros emisores
    deben poder entregar XML firmado directamente.

    La Partner API (`/partner/v1`) solo existe cuando el despliegue define
    `PSFE_PARTNER_API_ENABLED=true`; en caso contrario responde `404`. Toda
    respuesta JSON incluye `correlationId` (también en la cabecera
    `x-correlation-id`). Los errores usan `ErrorResponse`; un `429` incluye
    `Retry-After` en segundos.

    Si ZarelaFact no puede atender temporalmente (su base de datos o un servicio
    interno no responde), cualquier ruta, también la verificación de
    `X-API-KEY`/`X-PARTNER-KEY` y los receptores `/fe/*`, responde
    `503 SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`); nunca
    `401` ni `403`. Un `401` siempre es una credencial ausente o inválida.
servers:
  - url: https://api.zarelafact.com
    description: API ZarelaFact (cuenta directa y Partner)
tags:
  - name: Operacion
  - name: Documentos
  - name: Secuencias
  - name: Anulaciones
  - name: Inbound DGII
  - name: Certificacion
  - name: Publico DGII
  - name: Partner
  - name: Sandbox
security:
  - ApiKeyAuth: []
paths:
  /healthz:
    get:
      tags: [Operacion]
      security: []
      summary: Healthcheck publico del servicio.
      responses:
        '200':
          description: Servicio vivo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /readyz:
    get:
      tags: [Operacion]
      security: []
      summary: Readiness operativo con storage, migraciones y rate limit.
      responses:
        '200':
          description: Servicio listo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessResponse'
        '503':
          description: Servicio no listo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadinessResponse'
  /metrics:
    get:
      tags: [Operacion]
      security: []
      summary: Metricas Prometheus.
      responses:
        '200':
          description: Metricas en formato Prometheus text exposition.
          content:
            text/plain:
              schema:
                type: string
  /ri/{token}:
    get:
      tags: [Documentos]
      security: []
      summary: Enlace temporal a la representación impresa (PDF) que recibe el comprador por correo.
      description: >-
        Es el enlace del correo «Factura por correo al comprador», que la cuenta activa por
        ambiente. No lleva API key: el token firmado es la credencial y abre solo el PDF de
        ese e-CF, durante 30 días desde el envío y mientras su representación impresa siga
        entregable (e-CF aceptado o aceptado condicional por la DGII). Un enlace vencido
        responde `410` y uno inválido, o de un e-CF que ya no se entrega, `404`, ambos en
        texto plano para la persona que lo abre.
      parameters:
        - name: token
          in: path
          required: true
          schema: { type: string, maxLength: 1300 }
      responses:
        '200':
          description: PDF de la representación impresa, para abrir en el navegador.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '404':
          description: RI_LINK_INVALID o RI_NOT_DELIVERABLE (cabecera X-Error-Code).
          content:
            text/plain:
              schema: { type: string }
        '410':
          description: RI_LINK_EXPIRED; el enlace venció.
          content:
            text/plain:
              schema: { type: string }
  /Sandbox/documentos-ecf:
    get:
      tags: [Sandbox]
      security:
        - ApiKeyAuth: []
      summary: Lista los documentos del Sandbox de tu cuenta.
      description: >-
        Documentos simulados, sin certificado: no son e-CF, no se firman, no se envían a la
        DGII y no tienen validez fiscal. No cuentan para el plan ni se cobran, y se conservan
        30 días. Del más reciente al más antiguo. Requiere `ecf:read`, que trae la clave de
        TesteCF. Un `verdict` o un `documentType` que no existen responden `400
        INVALID_SANDBOX_DOCUMENTS_QUERY`; `limit` y `offset` que no son números se ignoran, y
        `limit` se acota entre 1 y 100.
      parameters:
        - $ref: '#/components/parameters/SandboxLimit'
        - $ref: '#/components/parameters/SandboxOffset'
        - $ref: '#/components/parameters/SandboxVerdict'
        - $ref: '#/components/parameters/SandboxDocumentType'
        - $ref: '#/components/parameters/SandboxSearch'
      responses:
        '200':
          description: Página de documentos del Sandbox.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SandboxDocumentsResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Sandbox]
      security:
        - ApiKeyAuth: []
      summary: Prueba un documento en el Sandbox y devuelve el veredicto simulado.
      description: >-
        Recibe el mismo JSON que TesteCF: raíz `ECF` o el contrato simplificado. ZarelaFact lo
        prevalida con las reglas de producción y simula el veredicto que daría la DGII
        (`accepted`, `accepted_conditional` o `rejected`), con sus razones. Sin certificado: no
        lo firma, no lo envía a la DGII y no crea un e-CF. Es simulado, sin validez fiscal, no
        cuenta para el plan y se conserva 30 días. Un documento rechazado también se guarda y
        responde `201`.
        Un e-NCF que ya usaste en tu Sandbox se rechaza (DGII 1209). Requiere `ecf:validate`.
        Un cuerpo vacío, un JSON inválido o un JSON que no es un objeto responde `400
        INVALID_JSON`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EcfSubmitRequest' }
      responses:
        '201':
          description: Documento guardado con su veredicto simulado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SandboxSubmitResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/SandboxDailyLimit'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /Sandbox/documentos-ecf/{documentId}:
    get:
      tags: [Sandbox]
      security:
        - ApiKeyAuth: []
      summary: Consulta un documento del Sandbox con sus razones.
      description: >-
        Requiere `ecf:read`. Un documento de otra cuenta, o un id que no existe, responde
        `404 DOCUMENT_NOT_FOUND`.
      parameters:
        - $ref: '#/components/parameters/SandboxDocumentId'
      responses:
        '200':
          description: Documento del Sandbox.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SandboxDocumentResponse' }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /Sandbox/documentos-ecf/{documentId}/xml:
    get:
      tags: [Sandbox]
      security:
        - ApiKeyAuth: []
      summary: Descarga el XML simulado del documento del Sandbox.
      description: >-
        XML sin firma digital, con un comentario que indica que es del Sandbox y que no se
        envió a la DGII. Sin validez fiscal. Responde `409 SANDBOX_DOCUMENT_NOT_PRINTABLE` si
        el JSON enviado no se pudo convertir en un e-CF.
      parameters:
        - $ref: '#/components/parameters/SandboxDocumentId'
      responses:
        '200':
          description: XML simulado del e-CF, sin firma.
          content:
            application/xml:
              schema: { type: string }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/SandboxNotPrintable'
        '422':
          $ref: '#/components/responses/SandboxRenderFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /Sandbox/documentos-ecf/{documentId}/pdf:
    get:
      tags: [Sandbox]
      security:
        - ApiKeyAuth: []
      summary: Descarga la representación impresa simulada del documento del Sandbox.
      description: >-
        PDF con la leyenda «SANDBOX ZARELAFACT — SIN VALIDEZ FISCAL», sin código de seguridad
        ni QR. Responde `409 SANDBOX_DOCUMENT_NOT_PRINTABLE` como el XML.
      parameters:
        - $ref: '#/components/parameters/SandboxDocumentId'
      responses:
        '200':
          description: Representación impresa simulada, en PDF.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/SandboxNotPrintable'
        '422':
          $ref: '#/components/responses/SandboxRenderFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-ecf:
    parameters:
      - $ref: '#/components/parameters/Environment'
    get:
      tags: [Documentos]
      summary: Lista los e-CF que emitiste.
      description: >-
        Del más reciente al más antiguo (por fecha de envío a ZarelaFact), por cursor:
        repite con `cursor` igual al `nextCursor` hasta que llegue `null`; los filtros se
        mantienen. Con `issueDateFrom` e `issueDateTo` recorres un período completo por
        `FechaEmision` y descargas cada XML firmado con
        `GET /{environment}/documentos-ecf/{documentReference}/xml`. No incluye las
        validaciones previas (`?validate=true`) ni los comprobantes reemplazados al
        reiniciar la certificación. Requiere `ecf:read`, que trae la clave estándar (en
        eCF, con producción activa). Un filtro, `limit` o `cursor` inválido responde
        `400 INVALID_ISSUED_DOCUMENTS_QUERY`.
      parameters:
        - $ref: '#/components/parameters/IssuedDocumentsIssueDateFrom'
        - $ref: '#/components/parameters/IssuedDocumentsIssueDateTo'
        - $ref: '#/components/parameters/IssuedDocumentsType'
        - $ref: '#/components/parameters/IssuedDocumentsStatus'
        - $ref: '#/components/parameters/ReceivedDocumentsLimit'
        - $ref: '#/components/parameters/ReceivedDocumentsCursor'
      responses:
        '200':
          description: Una página de e-CF emitidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssuedDocumentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Documentos]
      summary: Emite o pre-valida un e-CF.
      description: |
        Con `?validate=true` valida el mismo JSON sin firmar ni registrar una emision,
        sin crear TrackID y sin enviar a DGII. Sin `validate=true`, ZarelaFact
        requiere el eNCF asignado por el POS, persiste el documento y encola
        firma/envio asincrono para DGII.

        La emision corre la misma validacion que `validate=true` (estructura,
        calculos, cuadre y XSD oficial del tipo) antes de registrar el documento:
        si falla responde `422` y el eNCF queda libre. Un descuadre de montos por
        encima de la tolerancia DGII (RD$1 por linea; en los totales, RD$1 por
        cada linea del detalle) no es un `422`: la DGII lo deja Aceptado
        Condicional, asi que se emite con un aviso en `warnings`
        (`details.code = SQUARING_ABOVE_DGII_TOLERANCE`, con `declared`,
        `expected` y `toleranceCents`). Lo mismo con los subdescuentos y
        subrecargos de cada item, `MontoPeriodo` y `ValorPagar`.

        JSON DGII: `MontoItem` = cantidad x precio - `DescuentoMonto` +
        `RecargoMonto`; con `IndicadorMontoGravado` 1 la base de cada tasa es la
        suma de sus items dividida entre (1 + tasa); un descuento global con
        `IndicadorNorma1007` 1 no se resta de `MontoGravadoI1` (va en
        `ValorPagar`), divide la base I1 entre (1 + 18 % + tasas 002 y 004 del
        item) y exige `IndicadorMontoGravado` 1 (`details.code =
        NORMA_1007_REQUIRES_ITBIS_INCLUDED`); los items con
        `IndicadorFacturacion` 0 suman en `MontoNoFacturable`; `ITBIS1`, `ITBIS2` e
        `ITBIS3` declaran su tasa (18, 16 y 0); otra tasa se emite con el aviso `ITBIS_RATE_MISMATCH` (`warnings`); la
        seccion `OtraMoneda` exige `TipoCambio` > 0 (`EXCHANGE_RATE_INVALID`) y sus
        totales se avisan si no cuadran con los de pesos ÷ `TipoCambio`; una seccion
        `Paginacion` enviada se valida contra `TotalPaginas` y las lineas del
        detalle (`PAGINATION_INVALID`; el XML de ZarelaFact nunca la declara); los impuestos
        adicionales se recalculan con la formula de la DGII (aviso
        `SQUARING_ABOVE_DGII_TOLERANCE` si no cuadran) y los codigos ISC 006-039 sin
        `MontoImpuestoSelectivoConsumoEspecifico` (salvo a granel) responden `422`
        (`details.code = ISC_SPECIFIC_AMOUNT_REQUIRED`); la tasa trimestral del ISC
        especifico no se comprueba; `TotalITBIS` va
        siempre que exista un `TotalITBISn`; `TotalITBISRetenido` y
        `TotalISRRetencion` son la suma de las lineas; el ITBIS retenido de una
        linea no supera su ITBIS (`ITBIS_RETENTION_EXCEEDS_LINE_ITBIS`), el E41 solo
        retiene ISR en servicios (`ISR_RETENTION_REQUIRES_SERVICE`) y la percepcion
        se avisa (`PERCEPTION_REGIME_NOT_IN_FORCE`); con `MontoGravadoI1` o
        `MontoGravadoI2` mayor que cero, `TotalITBIS1`/`TotalITBIS2` es obligatorio
        (`details.code = TOTAL_ITBIS_REQUIRED`: sin el la DGII rechaza el e-CF),
        tambien en la nota de credito con `IndicadorNotaCredito` 1, que va sin
        ITBIS: `TotalITBIS1` y `TotalITBIS` en `0.00` y `MontoTotal` sin ITBIS
        (Informe Tecnico e-CF §10; la DGII la deja Aceptado Condicional, que es
        valido, y la respuesta trae el aviso `LATE_CREDIT_NOTE_WITHOUT_ITBIS`; el
        JSON DGII tambien admite el ITBIS calculado);
        las notas 33/34 solo
        admiten `CodigoModificacion` 1-3; `RNCComprador` e `IdentificadorExtranjero`
        se excluyen y una E32 de RD$250,000 o mas (y las notas que la modifican)
        requiere uno de los dos (`details.code = BUYER_ID_REQUIRED`); un monto,
        cantidad, precio o tasa con coma o con texto (`1,500.50`, `abc`) responde
        `422` en su campo (`details.code = DECIMAL_FORMAT_INVALID`): no se limpia
        ni se toma como 0, y un numero JSON valido vale lo mismo que su texto; las fechas
        `DD-MM-AAAA` deben existir en el calendario (`31-02-2026` responde `422`
        con `details.code = DATE_INVALID`).

        Contrato simplificado: las propiedades desconocidas responden `422`
        (`details.code = UNKNOWN_FIELD`); impuestos adicionales, varias formas de
        pago, `InformacionesAdicionales` y `Paginacion` no existen en el contrato
        simplificado y responden `422` (`details.code =
        SIMPLIFIED_CONTRACT_UNSUPPORTED`): esos comprobantes van en JSON DGII; `paymentType` `card` es contado
        (`TipoPago` 1) con `FormaPago` 3; una venta a credito (`credit`, `TipoPago`
        2) exige `dueDate`/`FechaLimitePago` salvo en E47 (`details.code =
        PAYMENT_DUE_DATE_REQUIRED`); `IndicadorEnvioDiferido` solo sale con
        `deferredSend: true` o con la autorizacion de envio diferido registrada en
        la cuenta; con `currency` distinta de DOP los montos estan en esa moneda,
        `exchangeRate` es obligatorio y el e-CF lleva `OtraMoneda`;
        `pricesIncludeTax: true` declara precios con ITBIS incluido
        (`IndicadorMontoGravado` 1, base = suma de los items / (1 + tasa),
        redondeo medio-arriba); `globalSurchargeAmount`/`globalSurchargePercent`
        es el recargo global (`TipoAjuste` R); y los nodos opcionales del XSD
        (orden de compra, factura y pedido internos, vendedor, contacto y correo
        del comprador, entrega, transporte y `DescripcionItem`) se validan con el
        XSD del tipo: si el tipo no tiene el nodo responde `422` en el campo.
        `issuer.phone` (y `TablaTelefonoEmisor` en JSON DGII) se emite como
        `TablaTelefonoEmisor`: hasta 3 telefonos con el formato `809-555-1234`;
        otro formato responde `422` (`details.code = ISSUER_PHONE_INVALID`).

        El RNC emisor debe coincidir con el de la cuenta fiscal autenticada; si no
        coincide responde `422` con un error en `issuer.rnc` (contrato simplificado)
        o `ECF.Encabezado.Emisor.RNCEmisor` (JSON DGII).

        La fecha de vencimiento de la secuencia (`FechaVencimientoSecuencia`) es
        obligatoria para E31, E33, E41, E43, E44, E45, E46 y E47 (XSD DGII) y no
        existe en E32/E34. ZarelaFact nunca la completa por omision: si falta o no es
        una fecha real responde `422`, tanto en preflight como al emitir, con un
        error en `sequenceExpirationDate` (contrato simplificado) o
        `ECF.Encabezado.IdDoc.FechaVencimientoSecuencia` (JSON DGII). En un E32 o E34
        el JSON DGII la rechaza con `422` y `details.code =
        SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE`; el contrato simplificado la omite
        con un aviso con ese codigo. El XML y el PDF nunca la llevan en esos tipos.
        Tambien responde `422` si es anterior a la fecha de emision (el eNCF ya
        estaba vencido, `details.code = SEQUENCE_EXPIRED_AT_ISSUE_DATE`) o si la
        cuenta registro el rango que contiene el eNCF con otro vencimiento
        (`details.code = SEQUENCE_EXPIRATION_RANGE_MISMATCH`); sin rango registrado
        no se compara. Sin bloquear, avisa en `warnings` si vence despues del 31-12
        del ano siguiente a la fecha de emision (`SEQUENCE_EXPIRATION_BEYOND_LEGAL_MAX`)
        o si ya vencio el dia del envio (`SEQUENCE_EXPIRED_AT_SEND_DATE`).

        La huella de replay del eNCF se calcula sobre el
        JSON tal como lo envia el ERP (antes de completarlo con el perfil del
        tenant); las huellas historicas siguen aceptandose.

        Con el padron de contribuyentes de la DGII cargado, el preflight y la
        emision agregan un aviso en `warnings` (nunca bloquean) cuando el RNC o la
        cedula del comprador no aparece en el padron
        (`details.code = BUYER_RNC_NOT_IN_DGII_REGISTRY`) o no esta ACTIVO
        (`details.code = BUYER_RNC_NOT_ACTIVE_IN_DGII`, con `details.status`). El
        digito verificador no es motivo de rechazo.

        Los marcadores `{{RNC}}`, `{{RAZON_SOCIAL}}`, `{{NOMBRE_COMERCIAL}}`,
        `{{FECHA_EMISION}}` y `{{FECHA_LIMITE_PAGO}}` se reemplazan con los datos
        de la cuenta (fechas en hora de RD) antes de validar. Cualquier otro
        marcador `{{...}}` que quede, como `{{NCF_MODIFICADO}}` o `{{RNC_COMPRADOR}}`, responde `422`
        con `details.code = UNRESOLVED_PLACEHOLDER` en el campo afectado.

        Con `Prefer: wait=N` (RFC 7240) la emision espera hasta N segundos a que
        la representacion impresa se pueda entregar: cuando la DGII devuelve el
        TrackID del e-CF, cuando responde Aceptado o Aceptado Condicional al
        resumen RFCE de una factura de consumo menor a RD$250,000 (Informe
        Tecnico e-CF v1.0, secciones 8 y 9.1) o si el documento queda en
        contingencia. Entonces responde `201` con `Preference-Applied`,
        `result.securityCode`, `result.qrUrl` y `result.printing` para imprimir;
        si no, el `202` de siempre con `Retry-After`. Firmar no basta. Un replay
        del mismo eNCF y JSON que ya se puede imprimir responde `201` sin
        esperar. La aceptacion final de un e-CF con TrackID sigue siendo
        asincrona.
      parameters:
        - name: validate
          in: query
          required: false
          schema:
            type: boolean
          description: Preflight sin efectos fiscales cuando es `true`.
        - $ref: '#/components/parameters/PreferWait'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EcfSubmitRequest'
            examples:
              dgiiShaped:
                summary: JSON con raiz ECF compatible DGII/XSD
                value:
                  ECF:
                    Encabezado:
                      Version: '1.0'
                      IdDoc:
                        TipoeCF: '31'
                        eNCF: E310000000001
                        FechaVencimientoSecuencia: 31-12-2028
                      Emisor:
                        RNCEmisor: '{{RNC}}'
                        RazonSocialEmisor: '{{RAZON_SOCIAL}}'
                      Comprador:
                        RNCComprador: '{{RNC_COMPRADOR}}'
                        RazonSocialComprador: '{{RAZON_SOCIAL_COMPRADOR}}'
                      Totales:
                        MontoTotal: 1180.00
                    DetallesItems:
                      Item:
                        - NumeroLinea: 1
                          NombreItem: Servicio de integracion
                          CantidadItem: 1
                          PrecioUnitarioItem: 1000.00
                          MontoItem: 1000.00
              simplified:
                summary: Contrato simplificado con los campos obligatorios
                value:
                  type: E31
                  encf: E310000000011
                  sequenceExpirationDate: 31-12-2028
                  issueDate: '2026-10-01T10:30:00-04:00'
                  issuer:
                    rnc: '{{RNC}}'
                    legalName: '{{RAZON_SOCIAL}}'
                    address: '{{DIRECCION_EMISOR}}'
                  buyer:
                    rnc: '{{RNC_COMPRADOR}}'
                    name: '{{RAZON_SOCIAL_COMPRADOR}}'
                  paymentType: credit
                  dueDate: '2026-10-31T10:30:00-04:00'
                  incomeType: '01'
                  lines:
                    - name: Servicio de soporte
                      quantity: 2
                      unitPrice: 1000
                      itbisRate: 18
                      itemKind: service
      responses:
        '200':
          description: Preflight completado cuando `validate=true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '201':
          $ref: '#/components/responses/SubmitSigned'
        '202':
          description: >-
            Documento registrado y encolado para procesamiento asincrono. Con
            `Prefer: wait=N`, la DGII no respondio dentro del plazo (o rechazo el
            resumen RFCE): trae `Retry-After` y `printing` llega en la consulta.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: eNCF existente con otro contenido o perteneciente a un rango anulado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validacion fiscal fallida, al prevalidar o al emitir (por ejemplo RNC emisor distinto del de la cuenta autenticada, en `issuer.rnc` o `ECF.Encabezado.Emisor.RNCEmisor`; fecha de vencimiento de la secuencia ausente o invalida (o enviada en E32/E34 en el JSON DGII), en `sequenceExpirationDate` o `ECF.Encabezado.IdDoc.FechaVencimientoSecuencia` con `details.code` `SEQUENCE_EXPIRATION_DATE_REQUIRED`/`SEQUENCE_EXPIRATION_DATE_INVALID`/`SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE`, anterior a la fecha de emision (`SEQUENCE_EXPIRED_AT_ISSUE_DATE`) o distinta del vencimiento del rango registrado en la cuenta que contiene el eNCF (`SEQUENCE_EXPIRATION_RANGE_MISMATCH`); descuento o recargo global en monto con `pricesIncludeTax`, con `details.code` `GLOBAL_AMOUNT_WITH_PRICES_INCLUDE_TAX`; propiedad desconocida del contrato simplificado con `details.code` `UNKNOWN_FIELD`; comprador sin identificar en una E32 de RD$250,000 o mas con `details.code` `BUYER_ID_REQUIRED`; nota de débito o crédito sobre un e-NCF de la cuenta que la DGII rechazó o que se anuló, con `details.code` `REFERENCED_ENCF_NOT_ACCEPTED`; `CodigoModificacion` (o `reference.modificationCode`) 4, el reemplazo de un comprobante de papel serie B emitido en contingencia, en cualquier tipo, con `details.code` `CONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTED` (ZarelaFact no lo emite; si la DGII no responde, el e-CF se emite igual y queda en contingencia electrónica, y ZarelaFact lo envía y reintenta solo); fuera de las notas, `InformacionReferencia` con código 5 fuera del 31 o sin un eNCF E32; nota sobre un e-CF de la cuenta emitida a otro comprador (`REFERENCED_BUYER_MISMATCH`), con una `FechaNCFModificado` distinta de su fecha de emisión (`REFERENCED_DATE_MISMATCH`) o, en una nota de crédito, que con las notas de crédito anteriores supera su monto total (`CREDIT_NOTES_EXCEED_ORIGINAL`); `FechaNCFModificado`/`reference.date` posterior a la fecha de emisión (`REFERENCE_DATE_AFTER_ISSUE_DATE`); en el JSON DGII, `IndicadorNotaCredito` distinto del que dan los días calendario entre `FechaNCFModificado` y `FechaEmision` (`CREDIT_NOTE_INDICATOR_MISMATCH`); `FechaHoraFirma`/`signatureDate` enviada por el cliente posterior a la hora actual de RD (margen de 2 minutos), en `ECF.FechaHoraFirma` o `signatureDate` con `details.code` `SIGNATURE_DATE_IN_FUTURE` (o `SIGNATURE_DATE_INVALID`); o XML que no cumple el XSD oficial, en `ECF`). Al emitir, un `422` no registra el documento. `errors` lista los campos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-ecf/status/batch:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Documentos]
      summary: Consulta estados por lote.
      description: >-
        Maximo 100 documentos por solicitud; recomendado 50. Cada resultado trae
        `lastError` cuando el documento no avanza: el ultimo fallo de envio a la
        DGII (por ejemplo `DGII_CERTIFICATE_NOT_DELEGATED` con su `hint`, o
        `DGII_RECEPTION_REJECTED` con `dgiiMessages`) o, en contingencia,
        `DGII_UNAVAILABLE`. El mismo error va en `errors`. Con estado final
        (`accepted`, `accepted_conditional`, `rejected`) o `cancelled`,
        `lastError` es null.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusBatchRequest'
      responses:
        '200':
          description: Estados encontrados y no encontrados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusBatchResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-ecf/{documentReference}/xml:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/DocumentReference'
    get:
      tags: [Documentos]
      summary: Descarga el XML firmado de un documento.
      description: >-
        Busca por `documentId` o por eNCF. Requiere el permiso `ecf:read` (incluido
        en las API keys nuevas). Responde `409 DOCUMENT_NOT_SIGNED` mientras el
        documento no está firmado. En `transmission_failed` el XML firmado se
        descarga como evidencia (`404` si nunca llegó a firmarse).
      responses:
        '200':
          description: XML firmado del e-CF.
          content:
            application/xml:
              schema: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-ecf/{documentReference}/pdf:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/DocumentReference'
    get:
      tags: [Documentos]
      summary: Descarga la representación impresa (PDF tamaño carta).
      description: >-
        El mismo PDF del portal, con QR, código de seguridad y fecha de firma.
        Busca por `documentId` o por eNCF y requiere `ecf:read`. Responde
        `409 DOCUMENT_NOT_SIGNED` mientras el documento no está firmado y
        `409 RI_AWAITING_DGII_RESPONSE` mientras la DGII no responde (TrackID del
        e-CF o respuesta del resumen RFCE; en contingencia se entrega con su
        leyenda). Si la DGII rechazó el resumen RFCE de una factura de consumo
        menor a RD$250,000 responde `409 RI_NOT_DELIVERABLE_REJECTED`, y un
        documento en `transmission_failed` (no llegó a la DGII) responde
        `409 RI_NOT_DELIVERABLE_NOT_TRANSMITTED`.
      responses:
        '200':
          description: PDF de la representación impresa.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-ecf/{documentId}/entrega-receptor/reconciliar:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: documentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Documentos]
      summary: Reconcilia una entrega e-CF incierta al receptor.
      description: |
        La entrega al comprador queda `uncertain` solo cuando, tras agotar sus
        reintentos (5), el receptor nunca respondió al envío. Persiste evidencia
        WORM y fija una sola vez `sent` o `dispatch_failed`. Para `sent` exige
        el ARECF firmado del receptor en `evidence.arecfXml`. Nunca reenvía el
        e-CF automáticamente.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FiscalReconciliationRequest'
      responses:
        '200':
          description: Entrega reconciliada o replay idempotente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationResponse'
        '409':
          description: Estado no incierto, resultado conflictivo o evidencia incompatible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/contingencia:
    parameters:
      - $ref: '#/components/parameters/Environment'
    get:
      tags: [Documentos]
      summary: Lista documentos diferidos por contingencia DGII.
      description: >-
        Documentos que esperan a que la DGII vuelva (sin respuesta, timeout, 5xx o
        autenticacion DGII caida). No hay ventana fija: se reintentan con espera
        creciente (5 min, el doble cada vez, hasta 30 min) y se envian cuando la DGII
        responde. A las 72 h sin llegar a la DGII ZarelaFact avisa a su operador y
        sigue reintentando. Cada documento trae `since`, `attempts`, `lastError`
        (mensaje) y `lastDeferredAt`.
      responses:
        '200':
          description: Documentos actualmente en contingencia.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContingencyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/secuencias:
    parameters:
      - $ref: '#/components/parameters/Environment'
    get:
      tags: [Secuencias]
      summary: Lista rangos eNCF del ambiente.
      responses:
        '200':
          description: Rangos eNCF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceRangesResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Secuencias]
      summary: Crea un rango eNCF activo para un tipo e-CF.
      description: |
        Registro operativo opcional. No es requisito para emitir ni para anular:
        el POS/ERP asigna el eNCF y la emision no reserva ni mueve el cursor del
        rango.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSequenceRangeRequest'
      responses:
        '201':
          description: Rango creado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SequenceRangeResponse'
        '409':
          description: Rango solapado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/anulaciones-ecf/prevalidar:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Anulaciones]
      summary: Pre-valida una ANECF sin enviarla a DGII.
      description: >-
        Construye la ANECF, valida su XSD y revisa los comprobantes del rango. Un e-CF
        firmado que nunca salió hacia la DGII ni hacia el comprador se puede anular;
        uno que llegó o pudo llegar bloquea el rango con `ANECF_DOCUMENT_CONFLICT`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnulmentRequest'
      responses:
        '200':
          description: ANECF construida y validada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '400':
          description: >-
            ANECF inválida, pedida en CerteCF (`ANECF_NOT_AVAILABLE_IN_CERTECF`; las
            anulaciones son de eCF y se prueban en TesteCF) o `ANECF_DOCUMENT_CONFLICT`
            con `details.conflicts[]` (`encf`, `documentId`, `status`, `reason`).
            `reason` es `document_already_submitted_or_dgii_validated`,
            `document_in_contingency` (se enviará a la DGII cuando se recupere),
            `document_dgii_submission_uncertain`, `document_dgii_submission_in_progress`
            o `document_already_delivered_to_receiver`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/anulaciones-ecf:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/IdempotencyKey'
    post:
      tags: [Anulaciones]
      summary: Crea una solicitud ANECF.
      description: >-
        Valida el rango como `prevalidar`, firma y envía la ANECF. Cuando la DGII la
        acepta, los comprobantes locales del rango que nunca llegaron a la DGII
        (firmados sin enviar) quedan `cancelled` con sus jobs y su e-NCF ya no se
        envía; la respuesta los lista en `coveredDocuments.cancelled`
        (`documentId`, `encf`). Los que pudieron llegar a la DGII van en
        `coveredDocuments.skipped` con su `reason` para revisión.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnulmentRequest'
      responses:
        '200':
          description: ANECF construida sin envio o replay idempotente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '202':
          description: ANECF enviada y aceptada por la DGII (`status` `accepted`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '400':
          description: >-
            ANECF inválida, pedida en CerteCF (`ANECF_NOT_AVAILABLE_IN_CERTECF`; las
            anulaciones son de eCF y se prueban en TesteCF) o `ANECF_DOCUMENT_CONFLICT`
            con `details.conflicts[].reason` (ver `prevalidar`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `ANECF_IDEMPOTENCY_CONFLICT`, `ANECF_RANGE_RESERVED` o
            `ANECF_DOCUMENT_CONFLICT` (un comprobante del rango llegó o pudo llegar a la
            DGII o al comprador mientras se registraba la anulación; `details.documentId`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            La DGII rechazó la ANECF (`ok: false`, `status: rejected`, mensajes en
            `dgii.mensajes`). Es un rechazo definitivo: los rangos quedan libres y se
            puede corregir y enviar otra vez con otra `Idempotency-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '502':
          description: >-
            Resultado incierto (`status: uncertain`): sin respuesta de la DGII, o una
            anulación parcial («anuladas correctamente. Con excepción…»). No la reenvíes;
            concíliala con `POST .../reconciliar`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '428':
          description: Falta `Idempotency-Key` para enviar la ANECF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/anulaciones-ecf/{annulmentId}:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: annulmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags: [Anulaciones]
      summary: Consulta una solicitud ANECF.
      responses:
        '200':
          description: Estado actual de la ANECF.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/anulaciones-ecf/{annulmentId}/reconciliar:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: annulmentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Anulaciones]
      summary: Reconcilia una ANECF incierta con evidencia durable.
      description: |
        Solo un resultado `uncertain` puede reconciliarse. La evidencia se
        persiste como artifact WORM y el resultado queda inmutable; no vuelve
        a enviar automáticamente a DGII.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FiscalReconciliationRequest'
      responses:
        '200':
          description: ANECF reconciliada o replay idempotente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationResponse'
        '409':
          description: Estado no incierto, outcome conflictivo o evidencia incompatible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-recibidos:
    parameters:
      - $ref: '#/components/parameters/Environment'
    get:
      tags: [Inbound DGII]
      summary: Lista los e-CF que tus proveedores te enviaron.
      description: >-
        Del más reciente al más antiguo, por cursor: repite con `cursor` igual al
        `nextCursor` hasta que llegue `null`. Requiere `ecf:read`, que trae la clave
        estándar (en eCF, con producción activa); responder la aprobación pide `tenant:admin`. Solo lista e-CF
        recibidos en `/fe/recepcion/api/ecf`: las ACECF que tus clientes envían sobre tus
        e-CF están en `GET /{environment}/aprobaciones-comerciales-recibidas` (y llegan con el
        webhook `document.commercial_approval_received`). Cada elemento
        trae la vista de la pantalla Recibidos del portal (`view`) y, mientras falte tu
        respuesta, `commercialApprovalDeadline`. Un filtro, `limit` o `cursor` inválido
        responde `400 INVALID_RECEIVED_DOCUMENTS_QUERY`.
      parameters:
        - $ref: '#/components/parameters/ReceivedDocumentsGroup'
        - $ref: '#/components/parameters/ReceivedDocumentsType'
        - $ref: '#/components/parameters/ReceivedDocumentsEncf'
        - $ref: '#/components/parameters/ReceivedDocumentsIssuerRnc'
        - $ref: '#/components/parameters/ReceivedDocumentsFrom'
        - $ref: '#/components/parameters/ReceivedDocumentsTo'
        - $ref: '#/components/parameters/ReceivedDocumentsLimit'
        - $ref: '#/components/parameters/ReceivedDocumentsCursor'
      responses:
        '200':
          description: Una página de e-CF recibidos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedDocumentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-recibidos/{inboundDocumentId}:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/InboundDocumentId'
    get:
      tags: [Inbound DGII]
      summary: Consulta un e-CF recibido.
      description: >-
        El mismo elemento de la lista. Requiere `ecf:read`. Un documento de otra
        cuenta, de otro ambiente o una ACECF responde `404 RECEIVED_DOCUMENT_NOT_FOUND` (las
        ACECF están en `/{environment}/aprobaciones-comerciales-recibidas/{inboundDocumentId}`).
      responses:
        '200':
          description: e-CF recibido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedDocumentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/documentos-recibidos/{inboundDocumentId}/xml:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/InboundDocumentId'
    get:
      tags: [Inbound DGII]
      summary: Descarga el XML de un e-CF recibido.
      description: >-
        El XML tal como lo envió el proveedor, como archivo `RNCEmisor` + e-NCF `.xml`.
        Sale de su copia inmutable, que se conserva 10 años, después de comprobar su
        SHA-256. Requiere `ecf:read`. Un envío rechazado sin firma verificada no guarda su XML:
        responde `404 RECEIVED_DOCUMENT_XML_NOT_AVAILABLE`.
      responses:
        '200':
          description: XML del e-CF recibido.
          content:
            application/xml:
              schema: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/aprobaciones-comerciales-recibidas:
    parameters:
      - $ref: '#/components/parameters/Environment'
    get:
      tags: [Inbound DGII]
      summary: Lista las aprobaciones comerciales (ACECF) que tus clientes enviaron sobre tus e-CF.
      description: >-
        Las ACECF recibidas en `/fe/aprobacioncomercial/api/ecf`: la aceptación o el rechazo
        comercial que tu cliente (el comprador) envió sobre un e-CF que emitiste. Del más
        reciente al más antiguo, por cursor: repite con `cursor` igual al `nextCursor` hasta
        que llegue `null`. Requiere `ecf:read`, como `GET /{environment}/documentos-recibidos`.
        `documentId` enlaza el e-CF emitido con ese e-NCF en el mismo ambiente (`null` si no
        está entre tus emitidos). Una ACECF que el receptor no recibió (`status` `rejected` o
        `duplicate`, con `notReceived`) no es una decisión de tu cliente: `decision` es
        `null`. Un filtro, `limit` o `cursor` inválido responde
        `400 INVALID_RECEIVED_DOCUMENTS_QUERY`.
      parameters:
        - $ref: '#/components/parameters/ReceivedCommercialApprovalsEncf'
        - $ref: '#/components/parameters/ReceivedCommercialApprovalsBuyerRnc'
        - $ref: '#/components/parameters/ReceivedDocumentsFrom'
        - $ref: '#/components/parameters/ReceivedDocumentsTo'
        - $ref: '#/components/parameters/ReceivedDocumentsLimit'
        - $ref: '#/components/parameters/ReceivedDocumentsCursor'
      responses:
        '200':
          description: Una página de ACECF recibidas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedCommercialApprovalsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '423':
          $ref: '#/components/responses/Locked'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/aprobaciones-comerciales-recibidas/{inboundDocumentId}:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/ReceivedCommercialApprovalId'
    get:
      tags: [Inbound DGII]
      summary: Consulta una aprobación comercial (ACECF) recibida.
      description: >-
        El mismo elemento de la lista. Requiere `ecf:read`. Una ACECF de otra cuenta, de otro
        ambiente o un e-CF recibido responde `404 RECEIVED_COMMERCIAL_APPROVAL_NOT_FOUND`.
      responses:
        '200':
          description: ACECF recibida.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceivedCommercialApprovalResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/aprobaciones-comerciales-recibidas/{inboundDocumentId}/xml:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - $ref: '#/components/parameters/ReceivedCommercialApprovalId'
    get:
      tags: [Inbound DGII]
      summary: Descarga el XML original de una aprobación comercial (ACECF) recibida.
      description: >-
        El ACECF firmado tal como lo envió tu cliente, como archivo `RNCComprador` + e-NCF
        `.xml`. Sale de su copia inmutable, que se conserva 10 años, después de comprobar su
        SHA-256 (si no cuadra, `500 RECEIVED_DOCUMENT_XML_INTEGRITY_FAILED`). Requiere
        `ecf:read`. Una ACECF rechazada sin firma verificada no guarda su XML: responde
        `404 RECEIVED_COMMERCIAL_APPROVAL_XML_NOT_AVAILABLE`.
      responses:
        '200':
          description: XML del ACECF recibido.
          content:
            application/xml:
              schema: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '423':
          $ref: '#/components/responses/Locked'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/inbound-dgii/{inboundId}/aprobacion-comercial:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: inboundId
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Inbound DGII]
      summary: Consulta aprobacion comercial de un e-CF recibido.
      responses:
        '200':
          description: Estado de aprobacion comercial.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialApprovalStatusResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Inbound DGII]
      summary: Genera y opcionalmente despacha ACECF.
      description: >-
        Firma el ACECF, lo envía a la DGII y después al emisor del e-CF. La URL del
        emisor sale del directorio DGII (TesteCF y eCF), consultado con el token DGII de
        la cuenta; `targetUrl` solo vale si el emisor no está en el directorio o en
        CerteCF (si está, otra URL responde `422 ACECF_TARGET_URL_NOT_ALLOWED`).
        `commercialApproval.dispatch` trae el status del emisor y hasta 4 KB de su
        cuerpo (`responseTruncated`, `responseBytes`), nunca sus cabeceras. Si el emisor declaró autenticación (`urlOpcional` en el
        directorio), el ACECF lleva su token Bearer obtenido con semilla +
        validacioncertificado; un fallo ahí deja la entrega en `dispatch_failed`, no
        incierta. En CerteCF no hay directorio: el ACECF va solo a la DGII, responde
        `200` con `commercialApproval.status` `signed` y `targetSource`
        `not_applicable`. En TesteCF el directorio de la DGII devuelve su emisor-receptor
        simulado para cualquier RNC; si el emisor es cliente de ZarelaFact con TesteCF y
        certificado activo, el ACECF va al receptor de TesteCF de ZarelaFact
        (`targetSource` `zarelafact_testecf`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommercialApprovalRequest'
      responses:
        '200':
          description: ACECF generado sin despacho al emisor (también en CerteCF, con `targetSource` `not_applicable`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialApprovalSubmitResponse'
        '202':
          description: ACECF firmado y despachado a la contraparte.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommercialApprovalSubmitResponse'
        '409':
          description: >-
            `COMMERCIAL_APPROVAL_DECISION_CONFLICT` (ya se envió otra decisión),
            `ACECF_DGII_SUBMISSION_UNCERTAIN` (un envío anterior a la DGII quedó incierto
            y debe conciliarse antes de otro intento) o `RECEIVED_ECF_NOT_VALID_IN_DGII`
            (aprobación `accept` de un e-CF que Consulta Estado reporta rechazado o no
            encontrado: la DGII solo recibe aprobaciones comerciales de e-CF que aceptó;
            `details.dgiiValidity`). No se bloquea en CerteCF, donde no hay Consulta
            Estado, ni mientras la validez no se ha consultado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            `ACECF_DGII_REJECTED`: la DGII rechazó la aprobación comercial (HTTP 4xx con
            mensajes, o «Aprobación comercial rechazada», código 2). Es definitivo y queda
            registrado con `details.dgiiSubmission` (`httpStatus`, `dgiiCodigo`,
            `dgiiEstado`, `dgiiMessages`, `rejectedAt`); se puede corregir y enviar otra vez.
            `ACECF_TARGET_URL_NOT_ALLOWED`: el emisor está en el directorio DGII y
            `targetUrl` no es su URL registrada (`details.directoryTargetUrl`).
            `COMMERCIAL_APPROVAL_DATE_INVALID`: `approvalDate` no es una fecha real, es
            anterior a la `FechaEmision` del e-CF recibido o posterior a la hora actual de RD
            más 5 minutos (`details.reason`: `invalid`, `before_issue_date` o `in_future`); no
            se firmó ni se envió nada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >-
            El emisor no recibió el ACECF (`CommercialApprovalSubmitResponse`):
            `retry_scheduled` si la causa es pasajera (408, 429, 5xx, su autenticación o la
            red; se reintenta solo con el mismo ACECF hasta 10 intentos en unas 2 horas, ver
            `commercialApproval.dispatch.nextAttemptAt`; repetir la decisión antes de ese
            momento no reenvía ni gasta intentos), `dispatch_failed` si fue definitiva
            o se agotaron los intentos (repetir la misma decisión lo reenvía), o `uncertain`
            si no se confirmó (consulta el estado y concilia antes de actuar). También
            `ACECF_DGII_SUBMISSION_UNCERTAIN`: no se pudo confirmar el envío a la DGII
            (`ErrorResponse`).
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/CommercialApprovalSubmitResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            `ACECF_DGII_CERTIFICATE_UNAVAILABLE` (no hay certificado activo para enviar a
            la DGII; no salió nada), `DIRECTORY_DGII_AUTH_FAILED` (no se obtuvo el token
            DGII para consultar el directorio), `DIRECTORY_ACCESS_TOKEN_MISSING` (consulta
            al directorio sin token), `DIRECTORY_FETCH_TIMEOUT` o `DIRECTORY_FETCH_FAILED`
            (el directorio DGII no respondió a tiempo o respondió con error; repite la misma
            decisión) o `ACECF_SIGNING_FAILED`. También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{environment}/inbound-dgii/{inboundId}/aprobacion-comercial/reconciliar:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: inboundId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Inbound DGII]
      summary: Reconcilia una entrega ACECF incierta con evidencia durable.
      description: |
        Solo un outbox ACECF en `uncertain` puede reconciliarse. La operación
        no reintenta la red y queda inmutable después de fijar el outcome.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FiscalReconciliationRequest'
      responses:
        '200':
          description: ACECF reconciliado o replay idempotente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationResponse'
        '409':
          description: Estado no incierto, outcome conflictivo o evidencia incompatible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion/prevalidar:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Certificacion]
      summary: Prevalida un set de certificacion sin crear un run.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificationSetRequest'
      responses:
        '200':
          description: Set valido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericOkResponse'
        '409':
          description: >-
            CERTIFICATION_OWN_SET_REQUIRED; `dgiiModel` antes de que la DGII acepte las
            aprobaciones comerciales. Las pruebas de datos usan el Excel de la DGII del
            contribuyente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Errores de importacion o prevalidacion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Certificacion]
      summary: Crea un run asincrono de certificacion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CertificationSetRequest'
      responses:
        '202':
          description: Run creado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationRunResponse'
        '400':
          description: INVALID_CERTIFICATION_REQUEST; `dgiiModel` no es booleano o viene junto a un set propio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            CERTIFICATE_NOT_ACTIVE (la cuenta no tiene un certificado activo),
            CERTIFICATION_OWN_SET_REQUIRED (`dgiiModel` antes de que la DGII acepte las
            aprobaciones comerciales: las pruebas de datos usan el Excel de la DGII del
            contribuyente) o CERTIFICATION_SET_ALREADY_USED (los e-NCF del set ya se enviaron).
            No se crea ningún comprobante.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Errores de importacion o prevalidacion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion/{runId}:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: runId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags: [Certificacion]
      summary: Consulta el estado de un run de certificacion.
      responses:
        '200':
          description: Estado del run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationStatusResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion/{runId}/evidencia:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: runId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags: [Certificacion]
      summary: Descarga el evidence pack codificado en base64.
      responses:
        '200':
          description: JSON con el ZIP en `content` base64 y su SHA-256.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationEvidenceResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion/reiniciar:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Certificacion]
      summary: Reinicia las pruebas de datos o la simulación.
      description: >-
        Detiene el run en curso y deja los comprobantes de esa parte como reemplazados (no se
        borran). El siguiente `POST /{environment}/certificacion` vuelve a enviar las pruebas de
        datos con los e-NCF del Excel de la DGII, o la simulación (`dgiiModel`) con un bloque nuevo.
        La postulación y la declaración jurada que firmaste no cambian. Solo en CerteCF.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [part]
              properties:
                part:
                  type: string
                  enum: [data, simulation]
                  description: '`data`: pruebas de datos. `simulation`: simulación.'
      responses:
        '200':
          description: Parte reiniciada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationRestartResponse'
        '400':
          description: CERTIFICATION_PART_INVALID o propiedades no permitidas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion/aprobaciones-comerciales:
    parameters:
      - $ref: '#/components/parameters/Environment'
    get:
      tags: [Certificacion]
      summary: Consulta el último envío de las aprobaciones comerciales de prueba.
      responses:
        '200':
          description: El último envío, o `commercialApprovals` null si todavía no hay ninguno.
          content:
            application/json:
              schema:
                type: object
                required: [ok, commercialApprovals]
                properties:
                  ok: { type: boolean }
                  environment: { type: string }
                  commercialApprovals:
                    oneOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/CommercialApprovalTests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Certificacion]
      summary: Envía las aprobaciones comerciales de prueba (paso 3 de CerteCF).
      description: >-
        Envía a la DGII, de una en una, las aprobaciones comerciales (ACECF) del Excel que
        descargaste en CerteCF con «DESCARGAR APROBACIONES COMERCIALES» (hoja
        ACEECF_Generadas), fila por fila y tal cual, firmadas con tu certificado. La DGII compara
        cada campo con ese Excel, incluida la fecha y hora de la aprobación (la de la descarga):
        usa el último que descargaste. Se detiene en el primer rechazo. Solo en CerteCF, con las
        pruebas de datos de e-CF aceptadas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [workbookBase64]
              properties:
                workbookBase64:
                  type: string
                  description: El Excel de aprobaciones comerciales de la DGII en base64 (máximo 700 KB).
      responses:
        '202':
          description: Envío en cola; consulta su avance con GET.
          content:
            application/json:
              schema:
                type: object
                required: [ok, commercialApprovals]
                properties:
                  ok: { type: boolean }
                  environment: { type: string }
                  correlationId: { type: [string, 'null'] }
                  commercialApprovals: { $ref: '#/components/schemas/CommercialApprovalTests' }
        '400':
          description: COMMERCIAL_APPROVAL_SET_REQUIRED (falta el Excel) o propiedades no permitidas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            COMMERCIAL_APPROVAL_SET_INVALID (no es el Excel de la DGII o una fila no cumple su
            formato) o COMMERCIAL_APPROVAL_SET_OTHER_TAXPAYER (el comprador del Excel es otro RNC).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            CERTIFICATION_DATA_TESTS_PENDING, CERTIFICATE_NOT_ACTIVE,
            COMMERCIAL_APPROVALS_IN_PROGRESS, CERTIFICATION_ENVIRONMENT_REQUIRED o
            CERTIFICATION_MANAGED_BY_PARTNER (tu proveedor de software lleva tu certificación).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/certificacion/documentos/{documentId}/reenviar:
    parameters:
      - $ref: '#/components/parameters/Environment'
      - name: documentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Certificacion]
      summary: Reenvía a la DGII un comprobante de las pruebas con un problema de envío.
      description: >-
        Para un comprobante que ya se firmó y la DGII no ha resuelto: sin respuesta
        (contingencia), un resumen RFCE que la DGII da por duplicado, consultas agotadas o sin
        novedad. Lo envía otra vez de inmediato, o consulta su estado si ya tiene TrackID. Un
        resumen que la DGII da por duplicado se consulta con ConsultaRFCE y se reenvía
        idéntico si la DGII no lo tiene; el E32 nunca se vuelve a firmar. Solo en CerteCF.
      responses:
        '202':
          description: Reenvío en cola.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CertificationResendResponse'
        '404':
          description: DOCUMENT_NOT_FOUND.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            DOCUMENT_ALREADY_ACCEPTED, DOCUMENT_REJECTED (reinicia esa parte de las pruebas),
            DOCUMENT_NOT_RESENDABLE (todavía no sale de la firma), DOCUMENT_SEND_IN_PROGRESS o
            DOCUMENT_SUPERSEDED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /{environment}/fe/recepcion/api/ecf:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Publico DGII]
      security: []
      summary: Recepcion publica de e-CF entrante.
      description: >-
        La DGII y los demás emisores envían el e-CF como archivo en el campo `xml` de un
        `multipart/form-data`; también se acepta el XML directo en el cuerpo, de hasta 5 MiB
        (mayor: `400 BODY_TOO_LARGE`, sin ARECF). La ruta no
        distingue mayúsculas y lleva el ambiente registrado en la DGII antes de `/fe`
        (`/CerteCF/fe/recepcion/api/ecf`): sin él, el e-CF recibe el ARECF `Estado` 1 con
        motivo 4 (o `400` si no se puede armar), y `?environment=` o cabeceras no cuentan. La respuesta es el ARECF firmado con el certificado del
        receptor: `Estado` 0 si se recibió y 1 con `CodigoMotivoNoRecibido` si no (1 error de
        especificación, 2 error de firma, 3 envío duplicado, 4 RNC comprador no corresponde).
        La firma es válida si sigue el «Firmado de e-CF» de la DGII: una sola firma, hija de
        la raíz, con `Reference URI=""` (todo el documento), transform enveloped-signature,
        C14N inclusivo, RSA-SHA256 y digest SHA-256, y un certificado vigente con el RNC, la
        cédula o el pasaporte de su titular en el SN (`serialNumber`); si no, motivo 2.
        Un XML mal formado (etiquetas, comentarios o CDATA sin cerrar, más de una raíz, más
        de 64 niveles, de 512 nombres de elemento distintos o de 10 000 elementos dentro de
        uno) es un error de especificación;
        uno sin `Signature` (fuera de comentarios), un error de firma.
        Repetir el mismo XML devuelve el mismo ARECF (`x-zarela-idempotent-replay: true`).
        Solo se recibe la raíz `ECF`: un `RFCE` va únicamente a la DGII y responde `400`
        `INVALID_XML_ROOT`. Si el comprador no es un contribuyente de ZarelaFact en ese
        ambiente, responde el ARECF `Estado` 1 con motivo 4, firmado con el certificado
        del RNC en otro ambiente si existe (`200`); sin ningún certificado con el que
        firmar responde `400` con ese ARECF sin firmar (`x-zarela-arecf-signed: false`).
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [xml]
              properties:
                xml:
                  type: string
                  format: binary
          application/xml:
            schema:
              type: string
      responses:
        '200':
          description: ARECF firmado (recibido o no recibido, según `Estado`).
          content:
            application/xml:
              schema:
                type: string
        '400':
          description: >-
            El envío no se pudo leer (UNSUPPORTED_CONTENT_TYPE, MISSING_XML_FIELD, INVALID_XML,
            INVALID_XML_ROOT para una raíz `RFCE`…), un XML sin los datos para armar un ARECF
            (INBOUND_TENANT_NOT_RESOLVED, o MISSING_SIGNATURE si además no trae firma; la
            respuesta es la misma sea o no cliente el RNC, sin `details`), o el
            ARECF motivo 4 sin firmar cuando el comprador
            no tiene ningún certificado en ZarelaFact (`application/xml`,
            `x-zarela-arecf-signed: false`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
            application/xml:
              schema:
                type: string
  /{environment}/fe/aprobacioncomercial/api/ecf:
    parameters:
      - $ref: '#/components/parameters/Environment'
    post:
      tags: [Publico DGII]
      security: []
      summary: Recepcion publica de ACECF.
      description: >-
        Como en la recepción de e-CF, el ACECF llega en el campo `xml` de un
        `multipart/form-data` o como XML directo, en la ruta con el ambiente; sin él
        responde `400`. La DGII lee el resultado en el código
        HTTP: 200 si se recibió y 400 si no (firma o formato inválidos; la firma se valida
        como en la recepción de e-CF). Una segunda
        aprobación del mismo e-CF se confirma con 200. Si el emisor del e-CF aprobado no es
        un contribuyente de ZarelaFact en ese ambiente, responde 400 con el acuse
        `Estado` 1 y motivo 4 (RNC comprador no corresponde). La recepción no depende del
        certificado del contribuyente: sin uno vigente el ACECF se recibe y se guarda igual,
        el acuse va sin firmar (`x-zarela-arecf-signed: false`) y se avisa al operador.
        El ACECF se compara con el e-CF emitido con ese e-NCF (RNCEmisor, RNCComprador y
        MontoTotal): si no hay e-CF emitido o algo no coincide se recibe igual y queda
        marcado en el documento recibido y en su evento.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [xml]
              properties:
                xml:
                  type: string
                  format: binary
          application/xml:
            schema:
              type: string
      responses:
        '200':
          description: ACECF recibido; el cuerpo es el acuse firmado.
          content:
            application/xml:
              schema:
                type: string
        '400':
          description: >-
            ACECF no recibido: el cuerpo es el acuse con `Estado` 1 y su motivo. Si el envío no
            se pudo leer, un ErrorResponse JSON.
          content:
            application/xml:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /partner/v1/webhook-endpoints/{endpointId}:
    parameters:
      - name: endpointId
        in: path
        required: true
        schema: { type: string, format: uuid }
    patch:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Edita configuración o estado de un endpoint propio.
      description: Cambiar URL exige endpoint previamente pausado, sin entregas running y una URL no registrada por el Partner. Las entregas pendientes se preparan con la URL vigente; los filtros solo afectan eventos futuros.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              additionalProperties: false
              properties:
                status: { type: string, enum: [active, paused, disabled] }
                url: { type: string, format: uri, maxLength: 2048 }
                name: { type: string, minLength: 1, maxLength: 200 }
                eventTypes: { type: array, minItems: 1, items: { type: string, minLength: 1 } }
      responses:
        '200':
          description: Endpoint actualizado sin secretos.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerWebhookEndpointResponse' }
        '409':
          description: WEBHOOK_EDIT_REQUIRES_PAUSE, WEBHOOK_DELIVERIES_IN_PROGRESS, WEBHOOK_URL_CONFLICT o WEBHOOK_ENDPOINT_RETIRED (el endpoint fue retirado con DELETE).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Deshabilita un endpoint conservando su historial.
      responses:
        '200':
          description: Baja lógica; no elimina entregas ni eventos.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerWebhookEndpointResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/webhook-deliveries:
    get:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Lista entregas propias con paginación por cursor.
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - name: cursor
          in: query
          schema: { type: string, maxLength: 256 }
        - name: status
          in: query
          schema: { type: string, enum: [queued, running, succeeded, failed] }
        - name: endpointId
          in: query
          schema: { type: string, format: uuid }
        - name: fiscalAccountId
          in: query
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Entregas ordenadas por creación descendente; cursor opaco o null al terminar.
          content:
            application/json:
              schema:
                type: object
                required: [deliveries, nextCursor]
                properties:
                  deliveries:
                    type: array
                    items: { $ref: '#/components/schemas/PartnerWebhookDeliveryResponse' }
                  nextCursor: { type: [string, 'null'] }
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/webhook-deliveries/{deliveryId}:
    get:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Consulta metadatos de una entrega propia.
      parameters:
        - name: deliveryId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Estado operativo sin payload fiscal, firma ni respuesta del receptor.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerWebhookDeliveryResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/webhook-deliveries/{deliveryId}/replay:
    post:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Reencola una entrega fallida de un endpoint activo.
      description: Conserva deliveryId, eventId y contador de intentos. Rechaza entregas queued/running/succeeded; el ERP debe deduplicar por eventId.
      parameters:
        - name: deliveryId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '202':
          description: Entrega reencolada.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerWebhookDeliveryResponse' }
        '409':
          description: WEBHOOK_REPLAY_NOT_ALLOWED; la entrega no está `failed` o su endpoint no está activo.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/certification/official-sets:
    get:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Descubre los sets oficiales de certificación habilitados.
      description: >-
        Devuelve referencias y huellas públicas; nunca expone rutas internas ni permite cargar
        sets arbitrarios. No incluye el set modelo de ZarelaFact (`dgii-model`), que solo se usa
        en la simulación: las pruebas de datos usan el Excel de la DGII del contribuyente,
        subido con `POST .../certification-test-sets`. `defaultRef` es null si PSFE no fijó uno.
      responses:
        '200':
          description: Catálogo activo y referencia recomendada.
          content:
            application/json:
              schema:
                type: object
                required: [defaultRef, sets]
                additionalProperties: false
                properties:
                  defaultRef: { type: [string, 'null'] }
                  correlationId: { type: string }
                  sets:
                    type: array
                    items:
                      type: object
                      required: [ref, sha256, format]
                      additionalProperties: false
                      properties:
                        ref: { type: string }
                        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
                        format: { type: string }
        '503':
          description: Catálogo oficial no disponible o inconsistente. También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /partner/v1/billing/usage:
    get:
      tags: [Partner]
      security: [{ PartnerKeyAuth: [] }]
      summary: Consulta el consumo aceptado por DGII de todas las Cuentas fiscales del Partner en el periodo de cobro o en un mes.
      description: >-
        Requiere production:read. Solo cuenta documentos eCF en estado accepted o
        accepted_conditional según acceptedAt; acceptedAt es la fechaRecepcion
        informada por DGII y, si DGII no la envía, la hora en que PSFE registró la
        aceptación. Sin `month` devuelve el periodo de cobro vigente del Partner:
        con un plan pagado en línea, el ciclo de su suscripción (se renueva el
        mismo día cada mes, `periodBasis: subscription`), que es lo que consume el
        cupo del plan; sin suscripción, el mes calendario de República Dominicana
        (`periodBasis: calendar_month`). Con `month` devuelve ese mes calendario de
        RD. Es una consulta operativa, no un ledger cerrado, cargo ni factura.
      parameters:
        - name: month
          in: query
          description: Mes AAAA-MM en hora de República Dominicana. Si se omite, usa el periodo de cobro vigente.
          schema: { type: string, pattern: '^20[0-9]{2}-(0[1-9]|1[0-2])$' }
      responses:
        '200':
          description: Volumen agregado del Partner para el periodo o el mes solicitado.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [month, periodStart, periodEnd, periodBasis, timeZone, volumeBasis, environment, acceptedDocuments, countedStatuses, invoice]
                properties:
                  month: { type: string, description: 'Mes pedido, o el mes de RD en que empieza el periodo de cobro.' }
                  periodStart: { type: string, format: date-time, description: 'Inicio del periodo en UTC (un mes de RD empieza a las 04:00Z; un ciclo, el día y la hora en que se pagó).' }
                  periodEnd: { type: string, format: date-time }
                  periodBasis: { type: string, enum: [subscription, calendar_month] }
                  timeZone: { type: string, enum: [America/Santo_Domingo] }
                  volumeBasis: { type: string, enum: [partner_aggregate] }
                  environment: { type: string, enum: [ecf] }
                  acceptedDocuments: { type: integer, minimum: 0 }
                  countedStatuses:
                    type: array
                    items: { type: string, enum: [accepted, accepted_conditional] }
                  invoice: { type: boolean, enum: [false] }
                  plan:
                    oneOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/PartnerPlanUsage'
                    description: Solo sin `month` (periodo vigente); con `month` es null.
                  correlationId: { type: string }
        '400':
          description: Mes o parámetros inválidos.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Lista las Cuentas fiscales del Partner.
      description: Colección paginada y aislada por la identidad de la credencial Partner.
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
        - name: offset
          in: query
          schema: { type: integer, minimum: 0, default: 0 }
        - name: status
          in: query
          schema: { type: string, enum: [active, suspended] }
      responses:
        '200':
          description: Cuentas fiscales visibles para el Partner autenticado.
          content:
            application/json:
              schema:
                type: object
                required: [items, pagination]
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PartnerAccountResponse'
                  pagination:
                    type: object
                    required: [limit, offset, hasMore, nextOffset]
                    properties:
                      limit: { type: integer }
                      offset: { type: integer }
                      hasMore: { type: boolean }
                      nextOffset: { type: [integer, 'null'] }
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/by-external-id/{externalTenantId}:
    put:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Provisiona o recupera una cuenta fiscal del ERP.
      description: >-
        El externalTenantId es la identidad estable del tenant en el ERP. La operacion es
        idempotente por pareja Partner + externalTenantId. Con el padron de
        contribuyentes de la DGII cargado, un alta nueva (o un RNC distinto del ya
        vinculado) exige que el RNC exista y este ACTIVO: si no, responde `422`
        `RNC_NOT_IN_DGII_REGISTRY` o `RNC_NOT_ACTIVE_IN_DGII` (con `details.status`).
        Reenviar el RNC ya vinculado no se bloquea. El digito verificador no es motivo
        de rechazo.


        Cambiar el RNC: mientras la cuenta nunca haya estado en produccion ni la haya
        solicitado (sin e-CF en eCF), repetir el PUT con otro RNC y
        `replacesFiscalAccountId` igual al `fiscalAccountId` actual libera la cuenta
        anterior y crea una nueva con el mismo externalTenantId. Sin
        `replacesFiscalAccountId`, otro RNC responde `409` `ACCOUNT_LINK_CONFLICT` (con
        `details.fiscalAccountId`), asi un RNC mal escrito no suelta la cuenta. Responde
        `201` con el `fiscalAccountId` nuevo y `replacedFiscalAccountId`; el id anterior
        deja de responder (`404`). La certificacion y el certificado van con el RNC: la
        cuenta nueva empieza desde subir el certificado. Responde `409`
        `FISCAL_ACCOUNT_IN_PRODUCTION` si la cuenta ya paso a produccion o la solicito,
        `CERTIFICATION_IN_PROGRESS` con un envio de certificacion en curso, esperando a la
        DGII o bloqueado, y `DOCUMENTS_IN_PROGRESS` con e-CF en proceso.
      parameters:
        - name: externalTenantId
          in: path
          required: true
          schema:
            type: string
            maxLength: 200
          description: Para el Partner Zarela ERP debe ser el UUID estable del tenant; otros Partners pueden usar un identificador opaco estable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerProvisionRequest'
      responses:
        '200':
          description: Cuenta ya existente y sincronizada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccountResponse'
        '201':
          description: Cuenta creada, o creada en reemplazo de la anterior al cambiar el RNC (trae `replacedFiscalAccountId`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          description: >-
            `RNC_NOT_IN_DGII_REGISTRY` (el RNC no aparece en el padron DGII) o
            `RNC_NOT_ACTIVE_IN_DGII` (figura con otro estado, en `details.status`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Consulta la cuenta fiscal provisionada.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Cuenta fiscal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccountResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    delete:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Libera una cuenta fiscal que nunca estuvo en produccion.
      description: >-
        Quita la cuenta de tu plataforma: deja de aparecer en el listado y su
        `fiscalAccountId` responde `404`. El RNC y el externalTenantId quedan libres para
        un alta nueva. Se cierra la certificacion abierta y se revoca el certificado
        instalado; los e-CF de prueba y la auditoria se conservan con el RNC. Solo antes
        de produccion: con la cuenta en produccion (o solicitada) responde `409`
        `FISCAL_ACCOUNT_IN_PRODUCTION` y la gestiona soporte de ZarelaFact. Tambien
        responde `409` `CERTIFICATION_IN_PROGRESS` o `DOCUMENTS_IN_PROGRESS` mientras haya
        envios en curso.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Cuenta liberada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerFiscalAccountReleaseResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            `FISCAL_ACCOUNT_IN_PRODUCTION` (con `details.productionState`),
            `CERTIFICATION_IN_PROGRESS` (con `details.state`) o `DOCUMENTS_IN_PROGRESS`
            (con `details.pendingJobs`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/profile:
    patch:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Actualiza los datos no identificadores de la cuenta fiscal.
      description: >-
        `fiscalEmail`, `phone`, `address`, `provinceCode` y `municipalityCode` (también
        los del alta) se usan para completar los datos del emisor que falten al emitir
        con el contrato simplificado; nunca sustituyen valores enviados en el documento.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerProfilePatch'
      responses:
        '200':
          description: Perfil actualizado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: RNC_CHANGE_REQUIRES_RECERTIFICATION; el RNC no se modifica mediante el perfil.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/status:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Obtiene el estado consolidado de certificacion y ambientes.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Estado consolidado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerAccountResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-sessions:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Enlace temporal a la pantalla de pasos de la certificación, para incrustarla en el ERP.
      description: >-
        Devuelve la URL de la misma pantalla de pasos del dashboard Partner para esta Cuenta
        fiscal: certificado, postulación, Excel de la DGII, envíos con el avance de la DGII,
        aprobaciones comerciales, simulación, PDF, facturas de consumo y pasos en la DGII. Solo
        se puede mostrar en un iframe desde browserOrigin (CSP frame-ancestors) y solo sirve
        para la certificación de esa Cuenta fiscal. Vence en expiresInMinutes y no se renueva:
        pide uno cada vez que el usuario abra la certificación. Si ZarelaFact tiene configurados
        los orígenes de integración del Partner, browserOrigin debe ser uno de ellos.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [browserOrigin]
              properties:
                browserOrigin:
                  type: string
                  format: uri
                  maxLength: 2048
                  pattern: '^https://'
                  description: Origen HTTPS exacto de la UI del Partner que muestra el iframe.
                expiresInMinutes:
                  type: integer
                  minimum: 5
                  maximum: 480
                  default: 120
      responses:
        '201':
          description: Enlace creado.
          content:
            application/json:
              schema:
                type: object
                required: [fiscalAccountId, url, browserOrigin, expiresAt]
                properties:
                  fiscalAccountId: { type: string, format: uuid }
                  url:
                    type: string
                    format: uri
                    description: Página de ZarelaFact con la certificación; lleva el token firmado en la ruta.
                  browserOrigin: { type: string }
                  expiresAt: { type: string, format: date-time }
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: BROWSER_ORIGIN_NOT_ALLOWED; browserOrigin no está entre los orígenes de integración del Partner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: >-
            CERTIFICATION_EMBED_UNAVAILABLE; la certificación incrustable no está configurada.
            También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certificate-upload-sessions:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Crea una sesion de carga temporal para el certificado .p12/.pfx.
      description: >-
        El backend del ERP declara el browserOrigin HTTPS exacto de su propia UI y
        entrega el uploadToken al navegador autorizado. PSFE vincula CORS a esa
        sesión; no requiere registrar el dominio con el proveedor. El ERP nunca
        debe persistir el certificado ni la contraseña en su backend.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [browserOrigin]
              properties:
                browserOrigin:
                  type: string
                  format: uri
                  maxLength: 2048
                  pattern: '^https://'
                  description: Origen HTTPS exacto de la UI del Partner, sin ruta, query, fragmento, credenciales ni wildcard.
      responses:
        '201':
          description: Sesion temporal creada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerUploadSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certificate-rotation-requests:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Crea una sesión temporal para reemplazar el certificado del tenant.
      description: Usa el mismo flujo de carga segura y browserOrigin por sesión que la instalación inicial. La sesión por sí sola no reemplaza el certificado activo.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [browserOrigin]
              properties:
                browserOrigin:
                  type: string
                  format: uri
                  maxLength: 2048
                  pattern: '^https://'
                  description: Origen HTTPS exacto de la UI del Partner, sin ruta, query, fragmento, credenciales ni wildcard.
      responses:
        '201':
          description: Sesión de rotación creada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerUploadSession'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certificate:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Consulta metadata del certificado de CerteCF.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Metadata sin material secreto.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/dgii-registration:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Datos que el contribuyente declara en su postulación DGII.
      description: >-
        Devuelve el software, el proveedor (ZARELA GROUP SRL, nombre comercial ZARELA GROUP,
        RNC 133816164) y las URLs
        de recepción y aprobación comercial que el tenant registra en el portal de
        certificación DGII para CerteCF y, al final, para eCF. Las URLs son la base del
        ambiente; DGII y los demás emisores les agregan `/fe/recepcion/api/ecf` y
        `/fe/aprobacioncomercial/api/ecf`. La URL de autenticación se deja en blanco.
        Requiere `certification:read`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Datos de postulación de la Cuenta fiscal.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerDgiiRegistration'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-xml-signatures:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Firma el XML de postulación o declaración jurada con el certificado del tenant.
      description: >-
        El ERP descarga del portal DGII el XML sin firmar y lo envía en Base64. PSFE lo
        firma con el certificado instalado de la Cuenta fiscal y devuelve el XML firmado
        para subirlo a DGII. Solo admite raíces `Postulacion*` (`postulation`) y
        `DeclaracionJurada*` (`sworn_declaration`), y el XML debe contener el RNC de la
        Cuenta fiscal: nunca firma e-CF, acuses ni semillas de autenticación. Requiere
        `certification:attest`. Firmar no registra la atestación: después de subir el
        archivo a DGII, registra `dgii_postulation_submitted` o `sworn_declaration_submitted`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [documentType, xmlBase64]
              additionalProperties: false
              properties:
                documentType:
                  type: string
                  enum: [postulation, sworn_declaration]
                xmlBase64:
                  type: string
                  contentEncoding: base64
                  description: XML generado por el portal DGII, sin firmar.
      responses:
        '200':
          description: XML firmado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationXmlSignature'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: CERTIFICATE_NOT_INSTALLED; carga primero el certificado del contribuyente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            INVALID_CERTIFICATION_XML, CERTIFICATION_XML_TYPE_NOT_ALLOWED,
            CERTIFICATION_XML_RNC_MISMATCH o CERTIFICATION_XML_SIGNING_FAILED.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/certificate-upload-sessions/{uploadId}:
    put:
      tags: [Partner]
      security: []
      summary: Carga el certificado usando el token temporal.
      description: >-
        Este endpoint recibe el certificado y su contraseña mediante multipart/form-data,
        y el token temporal en `Authorization: Upload <uploadToken>`; no usa X-PARTNER-KEY.
        `401` indica token ausente, inválido, vencido o ya usado; `403 PARTNER_INACTIVE`
        indica que el Partner fue suspendido o deshabilitado durante la sesión. `422` indica
        un certificado que no se pudo leer (CERTIFICATE_PASSWORD_INVALID, CERTIFICATE_FILE_INVALID,
        CERTIFICATE_PRIVATE_KEY_MISSING, CERTIFICATE_KEY_PAIR_NOT_FOUND) o que no sirve para
        firmar e-CF: vencido o aún no válido (CERTIFICATE_EXPIRED, CERTIFICATE_NOT_YET_VALID),
        sin el RNC, la cédula o el pasaporte del titular en el SN (CERTIFICATE_HOLDER_ID_MISSING)
        o con un uso de clave sin firma digital ni no repudio (CERTIFICATE_KEY_USAGE_INVALID).
        Un error del archivo o de la contraseña no gasta la sesión: admite cinco intentos y
        cada error trae `details.attemptsRemaining`.
      parameters:
        - name: uploadId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            pattern: '^Upload .+$'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file, passphrase]
              additionalProperties: false
              properties:
                file:
                  type: string
                  format: binary
                passphrase:
                  type: string
                  format: password
      responses:
        '201':
          description: Certificado recibido y validado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificateResponse'
        '413':
          description: CERTIFICATE_TOO_LARGE; el archivo supera `maxBytes` de la sesión.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Crea o recupera el caso de certificacion CerteCF.
      description: >-
        Solo existe un Caso activo por Cuenta fiscal. Repetir la llamada con el mismo
        `officialSetRef` devuelve `200` con el Caso activo o, si ya fue aprobado, con
        el Caso aprobado. Un Caso `failed`, `blocked` o `rejected` sigue activo hasta
        que operaciones PSFE lo cierre; después se abre uno nuevo con otro set oficial.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [officialSetRef]
              additionalProperties: false
              properties:
                officialSetRef:
                  type: string
                  description: >-
                    El `testSetRef` del Excel de la DGII subido para esta Cuenta fiscal o un set
                    oficial habilitado por PSFE. `dgii-model` responde 422
                    CERTIFICATION_OWN_SET_REQUIRED, salvo que repita un Caso que ya lo usa.
      responses:
        '201':
          description: Caso creado.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '200':
          description: Caso activo existente, o Caso ya aprobado con el mismo officialSetRef.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '409':
          description: CERTIFICATION_CASE_SET_CONFLICT; el Caso activo está vinculado a otro set oficial.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            CERTIFICATION_SET_NOT_OFFICIAL (la referencia no está en el catálogo configurado),
            CERTIFICATION_SET_ISSUER_MISMATCH (el set fue emitido para otro RNC; no se crea el
            Caso), CERTIFICATION_OWN_SET_REQUIRED (`dgii-model` no sirve para las pruebas de
            datos: sube el Excel de la DGII del contribuyente) o CERTIFICATION_SET_INVALID.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '503':
          description: >-
            CERTIFICATION_CATALOG_INVALID, CERTIFICATION_SET_NOT_CONFIGURED,
            CERTIFICATION_SET_UNAVAILABLE o CERTIFICATION_SET_INTEGRITY_FAILED; reintenta
            después o contacta a PSFE. También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Consulta el caso de certificacion.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      responses:
        '200':
          description: Caso de certificacion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/runs:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Lista los runs recientes para recuperar un runId después de una respuesta perdida.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      responses:
        '200':
          description: Runs del caso, más reciente primero.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerRunList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Ejecuta el set oficial de pruebas de CerteCF.
      description: PSFE selecciona el set oficial; el Partner no puede sustituirlo por casos arbitrarios.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - name: Idempotency-Key
          in: header
          required: true
          description: Identificador estable generado por el backend ERP para este intento lógico.
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                correlationId: { type: string, maxLength: 200 }
                b2bSimulation:
                  type: boolean
                  description: >-
                    Simula la aprobación comercial (ACECF) al terminar los lotes. Por omisión es
                    `true` en las pruebas de datos y `false` en la simulación.
      responses:
        '202':
          description: Run encolado, o el mismo run si se repite la Idempotency-Key con los mismos parámetros (`replayed=true`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerRunStarted'
        '409':
          description: >-
            IDEMPOTENCY_CONFLICT (clave reutilizada con otros parámetros),
            CERTIFICATION_CASE_NOT_READY (el Caso no está en certificate_ready,
            application_pending ni ready_for_tests) o CERTIFICATION_SET_ALREADY_USED
            (los eNCF del set oficial ya existen en CerteCF; `details.usedEncfCount` y
            hasta 20 `details.encfs`). Este último no se resuelve reintentando: reinicia las
            pruebas de datos o sube el set nuevo de la DGII. CERTIFICATION_OWN_SET_REQUIRED: el
            Caso usa `dgii-model` y le tocan las pruebas de datos; sube el Excel de la DGII y
            cambia el Caso a ese set con `POST .../official-set`.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: CERTIFICATION_SET_ISSUER_MISMATCH (el set no corresponde al RNC de la Cuenta fiscal) o CERTIFICATION_PREVALIDATION_FAILED (`details.results`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '503':
          description: >-
            CERTIFICATION_CATALOG_INVALID, CERTIFICATION_SET_NOT_CONFIGURED,
            CERTIFICATION_SET_UNAVAILABLE o CERTIFICATION_SET_INTEGRITY_FAILED; el set oficial
            no está disponible y el run no se creó. También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/runs/{runId}:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Consulta el run de certificacion.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - $ref: '#/components/parameters/CertificationRunId'
      responses:
        '200':
          description: Estado del run.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationRunStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/runs/{runId}/evidence:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Descarga la evidencia de certificacion en base64.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - $ref: '#/components/parameters/CertificationRunId'
      responses:
        '200':
          description: ZIP codificado en base64.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationEvidenceResponse'
        '409':
          description: La evidencia todavía no está disponible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/runs/{runId}/consumer-summaries:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Descarga una copia de los resúmenes RFCE enviados de las Facturas de Consumo menores a RD$250,000.
      description: >-
        El resumen (RFCE) firmado que la DGII aceptó de cada Factura de Consumo menor a
        RD$250,000 del run. Cada RFCE resume una sola factura (formato RFCE 32 de la DGII), con el
        nombre con que se envió: RNC emisor + e-NCF + `.xml`. Sin `encf` devuelve un ZIP con todos;
        con `encf`, ese XML solo. Es una copia de lo que ZarelaFact envió al servicio de resúmenes de
        la DGII: no se sube en el portal (en «Facturas de consumo < 250Mil» va el e-CF de
        `consumer-invoices`).
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - $ref: '#/components/parameters/CertificationRunId'
        - name: encf
          in: query
          required: false
          schema: { type: string, example: E320000000012 }
          description: Solo el XML de esa factura, sin ZIP.
      responses:
        '200':
          description: ZIP (o XML suelto con `encf`) codificado en base64.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerRfceSummaryXmlResponse'
        '409':
          description: NO_RFCE_SUMMARIES (el run no tiene Facturas de Consumo menores a RD$250,000 aceptadas).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/runs/{runId}/consumer-invoices:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Descarga el XML del e-CF de las Facturas de Consumo menores a RD$250,000.
      description: >-
        El XML firmado del e-CF completo (raíz ECF, XSD «e-CF 32») de cada Factura de Consumo
        menor a RD$250,000 aceptada en el run, con el nombre RNC emisor + e-NCF + `.xml`. Sin `encf`
        devuelve un ZIP; con `encf`, ese XML solo. Es lo que la DGII pide en «Facturas de consumo <
        250Mil» de CerteCF: cada XML por separado y del último run.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - $ref: '#/components/parameters/CertificationRunId'
        - name: encf
          in: query
          required: false
          schema: { type: string, example: E320000000012 }
          description: Solo el XML de esa factura, sin ZIP.
      responses:
        '200':
          description: ZIP (o XML suelto con `encf`) codificado en base64.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerRfceSummaryXmlResponse'
        '409':
          description: NO_CONSUMER_INVOICES (el run no tiene Facturas de Consumo menores a RD$250,000 aceptadas).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/runs/{runId}/printed-pdfs:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Descarga los PDF de la representación impresa del run.
      description: >-
        La representación impresa (PDF con QR) de cada comprobante aceptado, para subirla al portal
        de la DGII (según su guía, los de la simulación). Devuelve un ZIP en base64 con un PDF por
        comprobante; `exceedsDgiiLimit` avisa si pasa de los 10 MB que admite el portal de la DGII.
        Con `selection=dgii`, un solo PDF por casilla del paso 5 de CerteCF (tipos 31, 32 de
        RD$250,000 o más, 33, 34, 41, 43, 44, 45, 46, 47 y 32 menor a RD$250,000), numerado y con
        el nombre de la casilla ("01 - Tipo 31 - E310009002001.pdf"); `slots` dice cuál va en cada una.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - $ref: '#/components/parameters/CertificationRunId'
        - name: selection
          in: query
          required: false
          schema: { type: string, enum: [all, dgii], default: all }
          description: '`dgii`: un PDF por casilla del paso 5 de la DGII. `all`: todos.'
      responses:
        '200':
          description: ZIP codificado en base64.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerPrintedPdfsResponse'
        '409':
          description: NO_PRINTED_PDFS (el run todavía no tiene representaciones impresas).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/attestations:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Registra una atestacion humana del integrador.
      description: >-
        Una Atestación del contribuyente declara un paso externo completado; nunca
        equivale a una Aprobación DGII verificada. Cada `type` alimenta un campo del
        `checklist` (dgii_postulation_submitted → dgiiPostulationSubmitted,
        printed_representations_uploaded → printedRepresentationsUploaded,
        production_urls_submitted → productionUrlsSubmitted,
        sworn_declaration_submitted → swornDeclarationSubmitted,
        ofv_roles_configured → ofvRolesConfigured); la acción `submit_dgii_postulation`
        de `partnerActions` se cumple con `dgii_postulation_submitted`, que además mueve
        el Caso a `application_pending`. Con la evidencia del run lista y las cuatro
        atestaciones posteriores a las pruebas registradas (printed_representations_uploaded,
        production_urls_submitted, sworn_declaration_submitted y ofv_roles_configured),
        el sistema registra la Aprobación DGII verificada, el Caso pasa a `approved` y
        producción (eCF) se activa sola si el certificado está vigente. La postulación
        no hace falta para ese cierre: la DGII no acepta las pruebas de datos sin ella. Los pasos del sistema (certificate_validated,
        test_set_prevalidated, runner_passed, evidence_ready, dgii_approval_verified,
        production_active) devuelven `403 SYSTEM_ATTESTATION_FORBIDDEN`; un tipo
        desconocido devuelve `400 INVALID_ATTESTATION_TYPE`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, actorRef]
              additionalProperties: false
              properties:
                type:
                  type: string
                  enum:
                    - dgii_postulation_submitted
                    - printed_representations_uploaded
                    - production_urls_submitted
                    - sworn_declaration_submitted
                    - ofv_roles_configured
                actorRef: { type: string, maxLength: 200 }
                occurredAt: { type: string, format: date-time }
                evidenceRefs: { type: array, maxItems: 50, items: { type: string, maxLength: 500 } }
                notes: { type: string, maxLength: 4000 }
      responses:
        '201':
          description: Atestacion registrada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '200':
          description: Atestacion repetida idempotentemente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-test-sets:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Lista los sets de pruebas DGII subidos para la Cuenta fiscal.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Sets subidos, del más reciente al más antiguo.
          content:
            application/json:
              schema:
                type: object
                required: [fiscalAccountId, items]
                properties:
                  fiscalAccountId: { type: string, format: uuid }
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/PartnerCertificationTestSet' }
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Sube el set de pruebas que la DGII entregó al contribuyente.
      description: >-
        Envía el archivo tal como lo descargó tu cliente del portal de certificación
        de la DGII: el Excel (.xlsx) o el JSON en `contentBase64`, o el JSON como
        objeto en `set`. Máximo 700 KB. ZarelaFact lo procesa, comprueba que el
        emisor sea el RNC de la Cuenta fiscal, que sus eNCF no se hayan emitido en
        CerteCF y que cada comprobante pase la prevalidación local. Responde un
        `testSetRef` para crear el Caso (`officialSetRef`). El mismo archivo
        devuelve el set ya guardado (`200`, `replayed: true`). Un Excel con
        columnas que ZarelaFact no reconoce responde `422 CERTIFICATION_SET_INVALID`
        con la lista de columnas en `details`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                fileName: { type: string, maxLength: 200 }
                contentBase64:
                  type: string
                  description: Archivo .xlsx o .json en base64. Usa este campo o `set`, no ambos.
                set:
                  type: object
                  description: Set en JSON (`documents`). Usa este campo o `contentBase64`, no ambos.
      responses:
        '201':
          description: Set guardado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerCertificationTestSet' }
        '200':
          description: El mismo archivo ya estaba guardado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerCertificationTestSet' }
        '409':
          description: CERTIFICATION_SET_ALREADY_USED (sus eNCF ya se emitieron en CerteCF).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '413':
          description: CERTIFICATION_SET_TOO_LARGE (más de 700 KB).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            CERTIFICATION_SET_INVALID (no se pudo procesar), CERTIFICATION_SET_ISSUER_MISMATCH
            (el emisor no es el RNC de la Cuenta fiscal) o CERTIFICATION_PREVALIDATION_FAILED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/close:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Cierra el Caso para reiniciar las pruebas.
      description: >-
        Cierra el Caso salvo con un envío en curso (`prevalidating`, `running`),
        esperando a la DGII (`submitted_to_dgii`, `awaiting_dgii`), aprobado o
        bloqueado (ese lo cierra PSFE). Repetir la llamada devuelve el Caso cerrado
        con `replayed: true`. Después crea otro Caso con el `testSetRef` del set que vas
        a usar.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason: { type: string, maxLength: 1000 }
      responses:
        '200':
          description: 'Caso cerrado (closed = true).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '409':
          description: CERTIFICATION_CASE_NOT_CLOSABLE (el Caso no está fallido ni rechazado).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/restart:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Reinicia una parte de las pruebas sin cerrar el Caso.
      description: >-
        `part: data` reinicia las pruebas de datos y `part: simulation`, la simulación. Detiene
        el run en curso y deja los comprobantes de esa parte como reemplazados (no se borran):
        el siguiente run vuelve a enviar las pruebas de datos con los mismos e-NCF del set, o la
        simulación con un bloque nuevo. El Caso conserva su certificado y sus atestaciones
        (postulación, declaración jurada y las demás) y queda en `ready_for_tests`. No se
        reinicia un Caso aprobado, bloqueado o que espera a la DGII.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [part]
              properties:
                part: { type: string, enum: [data, simulation] }
      responses:
        '200':
          description: Caso listo para enviar otra vez, con `restart` y `parts`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '409':
          description: CERTIFICATION_CASE_NOT_RESTARTABLE (aprobado, bloqueado o esperando a la DGII).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/commercial-approvals:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Consulta el último envío de las aprobaciones comerciales de prueba de la Cuenta fiscal.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      responses:
        '200':
          description: El último envío, o `commercialApprovals` null si todavía no hay ninguno.
          content:
            application/json:
              schema:
                type: object
                required: [caseId, commercialApprovals]
                properties:
                  caseId: { type: string, format: uuid }
                  correlationId: { type: string }
                  commercialApprovals:
                    oneOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/CommercialApprovalTests'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Envía las aprobaciones comerciales de prueba (paso 3 de CerteCF).
      description: >-
        ZarelaFact envía a la DGII, de una en una, las aprobaciones comerciales (ACECF) del
        Excel que el contribuyente descargó en CerteCF con «DESCARGAR APROBACIONES COMERCIALES»
        (hoja ACEECF_Generadas), fila por fila y tal cual, firmadas con el certificado de la
        Cuenta fiscal. La DGII compara cada campo con ese Excel, incluida la fecha y hora de la
        aprobación (la de la descarga), así que va el último que descargó. Se detiene en el
        primer rechazo. Requiere las pruebas de datos de e-CF aceptadas y que el comprador del
        Excel sea la Cuenta fiscal. La misma `Idempotency-Key` con el mismo Excel devuelve el
        mismo envío (`replayed: true`).
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - name: Idempotency-Key
          in: header
          required: true
          description: Identificador estable generado por el backend ERP para este envío.
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [workbookBase64]
              properties:
                correlationId: { type: string, maxLength: 200 }
                workbookBase64:
                  type: string
                  description: El Excel de aprobaciones comerciales de la DGII en base64 (máximo 700 KB).
      responses:
        '202':
          description: Envío en cola; consulta su avance con GET o en `commercialApprovals` del Caso.
          content:
            application/json:
              schema:
                type: object
                required: [caseId, replayed, commercialApprovals]
                properties:
                  caseId: { type: string, format: uuid }
                  correlationId: { type: string }
                  replayed: { type: boolean }
                  commercialApprovals: { $ref: '#/components/schemas/CommercialApprovalTests' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            CERTIFICATION_DATA_TESTS_PENDING, CERTIFICATE_NOT_ACTIVE,
            COMMERCIAL_APPROVALS_IN_PROGRESS o IDEMPOTENCY_CONFLICT.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            COMMERCIAL_APPROVAL_SET_INVALID (no es el Excel de la DGII o una fila no cumple su
            formato) o COMMERCIAL_APPROVAL_SET_OTHER_TAXPAYER (el comprador del Excel no es la
            Cuenta fiscal).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/official-set:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Cambia el set de pruebas del Caso sin cerrarlo.
      description: >-
        Para cuando la DGII le entrega al contribuyente un set nuevo (por ejemplo, tras reiniciar
        todo desde cero en su portal): sube el Excel con `POST .../certification-test-sets` y
        cambia el Caso a ese `testSetRef`. Las pruebas de datos se
        reinician con el set nuevo: los comprobantes del set anterior quedan reemplazados y el
        siguiente run usa los e-NCF y los datos del set nuevo. El Caso conserva su certificado y
        sus atestaciones. Pedir el set que ya usa devuelve el Caso sin cambios.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [officialSetRef]
              properties:
                officialSetRef:
                  type: string
                  description: 'El `testSetRef` de un set subido para esta Cuenta fiscal.'
      responses:
        '200':
          description: Caso con el set nuevo, listo para enviar las pruebas de datos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationCase'
        '409':
          description: CERTIFICATION_CASE_NOT_RESTARTABLE (aprobado, bloqueado o esperando a la DGII).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            CERTIFICATION_SET_NOT_OFFICIAL, CERTIFICATION_SET_ISSUER_MISMATCH (el set no es de
            esta Cuenta fiscal) o CERTIFICATION_OWN_SET_REQUIRED (`dgii-model` no sirve para las
            pruebas de datos).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/certification-cases/{caseId}/documents/{documentId}/resend:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Reenvía a la DGII un comprobante de las pruebas con un problema de envío.
      description: >-
        Para un comprobante del Caso que ya se firmó y la DGII no ha resuelto: sin respuesta
        (contingencia), un resumen RFCE que la DGII da por duplicado, consultas agotadas o sin
        novedad (`resendable: true` en el run). Lo envía otra vez de inmediato, o consulta su
        estado si ya tiene TrackID. Un resumen que la DGII da por duplicado se consulta con
        ConsultaRFCE y se reenvía idéntico si la DGII no lo tiene; el E32 nunca se vuelve a
        firmar. Un comprobante rechazado no se reenvía: reinicia esa parte de las pruebas.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/CertificationCaseId'
        - name: documentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '202':
          description: Reenvío en cola.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerCertificationResend'
        '409':
          description: >-
            DOCUMENT_ALREADY_ACCEPTED, DOCUMENT_REJECTED, DOCUMENT_NOT_RESENDABLE,
            DOCUMENT_SEND_IN_PROGRESS o DOCUMENT_SUPERSEDED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production-activation-requests:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Activa produccion de una Cuenta fiscal certificada.
      description: >-
        Normalmente no hace falta: producción se activa sola cuando el Caso queda
        `approved`. Úsalo para reintentar la activación (por ejemplo, tras cargar un
        certificado nuevo). Con un Caso `approved` y certificado vigente la respuesta
        trae `state: active`. Sin certificado vigente responde
        `409 CERTIFICATE_NOT_ACTIVE` y no queda ninguna solicitud pendiente. Si PSFE
        suspendió la Cuenta fiscal, la solicitud queda en `activation_requested`
        hasta la decisión de PSFE.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [certificationCaseId]
              additionalProperties: false
              properties:
                certificationCaseId: { type: string, format: uuid }
                notes: { type: string, maxLength: 4000 }
                evidenceRefs: { type: array, maxItems: 50, items: { type: string, maxLength: 500 } }
      responses:
        '201':
          description: Producción activada (o solicitud pendiente de PSFE si la Cuenta fiscal estaba suspendida).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerProductionState'
        '200':
          description: Solicitud pendiente repetida idempotentemente.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerProductionState'
        '409':
          description: CERTIFICATION_NOT_APPROVED (el Caso no está aprobado), CERTIFICATE_NOT_ACTIVE (sin certificado vigente) o PRODUCTION_STATE_CONFLICT (producción ya está activa).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Consulta la autorizacion de produccion.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Estado de produccion.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerProductionState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/documents:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Prevalida o emite un e-CF en produccion para la cuenta fiscal.
      description: El ERP conserva y asigna el eNCF. `validate=true` funciona antes de activar eCF y no reserva secuencia, firma, crea un job fiscal, envia a DGII ni emite webhooks `document.state_changed`; PSFE puede conservar un registro preflight_validated solo para auditoria. La emision normal exige produccion activa y es asincrona, y corre antes la misma validacion que `validate=true` (estructura, cuadre y XSD oficial); si falla responde `422` sin registrar el documento. Las reglas del JSON DGII y del contrato simplificado son las de `POST /{environment}/documentos-ecf`, igual que la cabecera `Prefer` con `wait=N` para recibir los datos de impresion en un `201`. Los marcadores `{{RNC}}`, `{{RAZON_SOCIAL}}`, `{{NOMBRE_COMERCIAL}}`, `{{FECHA_EMISION}}` y `{{FECHA_LIMITE_PAGO}}` se completan con los datos de la Cuenta fiscal; cualquier otro marcador `{{...}}` responde `422 UNRESOLVED_PLACEHOLDER`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: validate
          in: query
          required: false
          schema: { type: boolean, default: false }
        - $ref: '#/components/parameters/PreferWait'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [document]
              properties:
                document:
                  $ref: '#/components/schemas/EcfSubmitRequest'
      responses:
        '200':
          description: Preflight valido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '201':
          $ref: '#/components/responses/SubmitSigned'
        '202':
          description: >-
            Documento encolado. Con `Prefer: wait=N`, la DGII no respondio
            dentro del plazo y trae `Retry-After`.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '409':
          description: ENCF_PAYLOAD_MISMATCH (salvo el reenvio de un e-CF rechazado con `secuenciaUtilizada` false, corregido o con el mismo JSON, que se emite con `result.replacesDocumentId`), ENCF_REPLAY_UNVERIFIABLE o ENCF_ANNULLED para el eNCF enviado; ENCF_NOT_IN_REGISTERED_RANGE si la cuenta registro rangos de ese tipo en el ambiente y el eNCF no cae en ninguno (`details.registeredRanges`), o ENCF_RANGE_DISABLED si solo cae en un rango deshabilitado (tambien al prevalidar). Sin rangos registrados del tipo se emite con el aviso `ENCF_RANGE_NOT_REGISTERED` en `warnings`.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: Validación fiscal fallida; `errors` lista los campos. Un RNC emisor distinto del de la Cuenta fiscal se reporta en `ECF.Encabezado.Emisor.RNCEmisor` o `issuer.rnc`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '423':
          description: PRODUCTION_NOT_ACTIVE; la emisión normal se intentó antes de autorizar producción. No aplica al preflight `validate=true`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/documents/{documentId}:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Consulta el estado de un documento de produccion.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: documentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Estado del documento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerDocumentStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/documents/{documentId}/xml:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Descarga el XML firmado de un documento de producción.
      description: Responde `409 DOCUMENT_NOT_SIGNED` mientras el documento no está firmado.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: documentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: XML firmado del e-CF.
          content:
            application/xml:
              schema: { type: string }
        '409':
          description: DOCUMENT_NOT_SIGNED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/documents/{documentId}/pdf:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Descarga la representación impresa (PDF) de un documento de producción.
      description: Responde `409 DOCUMENT_NOT_SIGNED` mientras el documento no está firmado, `409 RI_AWAITING_DGII_RESPONSE` mientras la DGII no responde (TrackID del e-CF o respuesta del resumen RFCE), `409 RI_NOT_DELIVERABLE_REJECTED` si la DGII rechazó el resumen RFCE y `409 RI_NOT_DELIVERABLE_NOT_TRANSMITTED` si el documento está en `transmission_failed`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: documentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: PDF tamaño carta con QR, código de seguridad y fecha de firma.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '409':
          description: DOCUMENT_NOT_SIGNED, RI_AWAITING_DGII_RESPONSE, RI_NOT_DELIVERABLE_REJECTED o RI_NOT_DELIVERABLE_NOT_TRANSMITTED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: RI_GENERATION_FAILED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/annulments:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Lista las anulaciones (ANECF) del cliente en producción.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Anulaciones, de la más reciente a la más antigua.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Anula eNCF que el cliente no usará (ANECF).
      description: >-
        Firma y envía la ANECF a la DGII de producción. Requiere producción activa
        (`423 PRODUCTION_NOT_ACTIVE`) y la cabecera `Idempotency-Key`
        (`428 IDEMPOTENCY_KEY_REQUIRED`). No exige rangos registrados: la DGII
        comprueba que las secuencias sean del RNC. Responde como la anulación de la
        API directa: `202` si la DGII la acepta; `422` con el cuerpo de la anulación
        (`ok: false`, `status: rejected`, `dgii.mensajes`) si la DGII la rechaza, un
        rechazo definitivo que libera los rangos; y `502` con `status: uncertain` si
        no hubo respuesta o la anulación fue parcial (no la reenvíes). Un e-CF
        firmado que nunca salió hacia la DGII ni hacia el comprador se puede anular:
        al aceptarse la ANECF queda `cancelled` y no se envía
        (`coveredDocuments.cancelled`); lo que pudo llegar va en
        `coveredDocuments.skipped`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, maxLength: 128 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ranges]
              properties:
                ranges:
                  type: array
                  description: Bloques a anular por tipo; desde y hasta son eNCF completos.
                  items:
                    type: object
                    required: [ecfType, sequences]
                    properties:
                      ecfType: { type: string, pattern: '^E[0-9]{2}$' }
                      sequences:
                        type: array
                        items:
                          type: object
                          required: [desde, hasta]
                          properties:
                            desde: { type: string }
                            hasta: { type: string }
      responses:
        '200':
          description: 'Anulación repetida con la misma clave (`idempotent: true`).'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '202':
          description: La DGII aceptó la anulación; `coveredDocuments` lista los comprobantes cancelados.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '409':
          description: >-
            ANECF_RANGE_RESERVED, ANECF_IDEMPOTENCY_CONFLICT o ANECF_DOCUMENT_CONFLICT (un
            comprobante del rango llegó o pudo llegar a la DGII o al comprador).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            Datos inválidos. Un rechazo de la DGII también responde `422`, con el cuerpo
            de la anulación en vez de un error (ver la descripción).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '423':
          description: PRODUCTION_NOT_ACTIVE.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '428':
          description: IDEMPOTENCY_KEY_REQUIRED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/annulments/prevalidate:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Prevalida una anulación sin enviarla.
      description: >-
        Construye la ANECF, valida el XSD y revisa los comprobantes del rango. Un e-CF
        firmado que nunca salió hacia la DGII ni hacia el comprador se puede anular; uno
        que llegó o pudo llegar responde `400 ANECF_DOCUMENT_CONFLICT` con
        `details.conflicts[].reason`: `document_already_submitted_or_dgii_validated`,
        `document_in_contingency`, `document_dgii_submission_uncertain`,
        `document_dgii_submission_in_progress` o `document_already_delivered_to_receiver`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ranges]
              properties:
                ranges:
                  type: array
                  description: Bloques a anular por tipo; desde y hasta son eNCF completos.
                  items:
                    type: object
                    required: [ecfType, sequences]
                    properties:
                      ecfType: { type: string, pattern: '^E[0-9]{2}$' }
                      sequences:
                        type: array
                        items:
                          type: object
                          required: [desde, hasta]
                          properties:
                            desde: { type: string }
                            hasta: { type: string }
      responses:
        '200':
          description: ANECF construida y válida.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '422':
          description: Error de validación.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/annulments/{annulmentId}:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Consulta una anulación.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: annulmentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Estado de la anulación y respuesta de la DGII.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/sequences:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Lista los rangos autorizados registrados (opcional; anular no los exige).
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      responses:
        '200':
          description: Rangos registrados del ambiente eCF del cliente.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Registra un rango de eNCF autorizado por la DGII.
      description: >-
        Registro opcional: anular no lo exige y ZarelaFact no numera los e-CF.
        Si ya hay un rango vigente del mismo tipo que no se solapa, ese queda
        cerrado.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ecfType, rangeStart, rangeEnd]
              properties:
                ecfType: { type: string, pattern: '^E[0-9]{2}$' }
                rangeStart: { type: integer, minimum: 1 }
                rangeEnd: { type: integer, minimum: 1 }
                encfLength: { type: integer, description: 'Longitud total del eNCF (13).' }
                expiresAt: { type: string, format: date-time }
      responses:
        '201':
          description: Rango registrado; `replacedRangeId` indica el rango que quedó cerrado.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '409':
          description: SEQUENCE_RANGE_ACTIVE_EXISTS (se solapa con el rango vigente) o SEQUENCE_RANGE_OVERLAP (se solapa con un rango agotado o deshabilitado del mismo tipo y ambiente; los rangos autorizados no se repiten).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/inbound-documents:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Lista los e-CF que los proveedores enviaron al cliente.
      description: >-
        También llegan como webhook `document.received`. Solo los de producción (eCF); los
        de TesteCF están en `.../testecf/inbound-documents`. Del más reciente al más antiguo,
        con el cursor, los filtros y los elementos de `GET /{environment}/documentos-recibidos`
        de la API directa. Los campos de antes (`inboundDocumentId`, `encf`, `issuerRnc`,
        `receiverRnc`, `status`, `commercialApproval`, `receivedAt`) no cambian; se agregan
        `group`, `commercialApprovalDeadline`, `view` y `nextCursor`. Un `limit` no
        numérico usa 50.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/ReceivedDocumentsGroup'
        - $ref: '#/components/parameters/ReceivedDocumentsType'
        - $ref: '#/components/parameters/ReceivedDocumentsEncf'
        - $ref: '#/components/parameters/ReceivedDocumentsIssuerRnc'
        - $ref: '#/components/parameters/ReceivedDocumentsFrom'
        - $ref: '#/components/parameters/ReceivedDocumentsTo'
        - $ref: '#/components/parameters/ReceivedDocumentsLimit'
        - $ref: '#/components/parameters/ReceivedDocumentsCursor'
      responses:
        '200':
          description: e-CF recibidos con su estado de aprobación comercial.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerReceivedDocumentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/inbound-documents/{inboundDocumentId}:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Consulta un e-CF que un proveedor envió al cliente.
      description: >-
        El mismo elemento de la lista, más `fiscalAccountId`, como
        `GET /{environment}/documentos-recibidos/{inboundDocumentId}` de la API directa. Sirve
        para refrescar un documento (por ejemplo, después de aceptarlo o rechazarlo) sin
        recorrer la lista. Requiere `documents:read` y, como la lista, no exige producción
        activa: si la Cuenta fiscal sale de producción, sus compras se siguen leyendo. Un
        documento de otra Cuenta fiscal, de TesteCF o una ACECF responde
        `404 RECEIVED_DOCUMENT_NOT_FOUND`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/InboundDocumentId'
      responses:
        '200':
          description: e-CF recibido con su estado de aprobación comercial.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerReceivedDocumentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/inbound-documents/{inboundDocumentId}/xml:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Descarga el XML de un e-CF que un proveedor envió al cliente.
      description: >-
        Los bytes tal como los envió el proveedor, como archivo `RNCEmisor` + e-NCF `.xml`,
        igual que `GET /{environment}/documentos-recibidos/{inboundDocumentId}/xml` de la API
        directa. Sale de su copia inmutable, que se conserva 10 años, después de comprobar su
        huella SHA-256. Trae lo que hace falta para registrar la compra: líneas, cantidades,
        precios, ITBIS, totales y fecha límite de pago. El webhook `document.received` trae
        este enlace en `resource.xmlUrl`. Requiere `documents:read` y no exige producción
        activa. Un documento de otra Cuenta fiscal o de TesteCF responde
        `404 RECEIVED_DOCUMENT_NOT_FOUND`;
        un envío rechazado sin firma verificada no guarda su XML y responde
        `404 RECEIVED_DOCUMENT_XML_NOT_AVAILABLE`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/InboundDocumentId'
      responses:
        '200':
          description: XML del e-CF recibido.
          content:
            application/xml:
              schema: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: >-
            RECEIVED_DOCUMENT_XML_INTEGRITY_FAILED: la copia guardada no coincide con su huella
            SHA-256, así que no se entrega. Escríbenos con el `correlationId`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/inbound-documents/{inboundDocumentId}/commercial-approval:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Acepta o rechaza comercialmente un e-CF recibido (ACECF).
      description: >-
        Igual que la aprobación comercial de la API directa; requiere producción activa.
        El ACECF va a la DGII y después al emisor, cuya URL sale del directorio DGII
        consultado con el token DGII del cliente. Un e-CF recibido en TesteCF responde
        `404` aquí: se responde en `.../testecf/inbound-documents/{inboundDocumentId}/commercial-approval`. `202` si llegó al emisor; `502` si el
        despacho al emisor falló o quedó incierto (el cuerpo trae `commercialApproval`)
        o si no se pudo confirmar el envío a la DGII
        (`ACECF_DGII_SUBMISSION_UNCERTAIN`).
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: inboundDocumentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: { type: string, enum: [accept, reject] }
                rejectionReason: { type: string, maxLength: 250 }
      responses:
        '200':
          description: ACECF firmada y enviada (o registrada).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '202':
          description: ACECF firmada, aceptada por la DGII y entregada al emisor.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '409':
          description: >-
            La aprobación ya se envió con otra decisión, o un envío anterior a la DGII
            quedó incierto (`ACECF_DGII_SUBMISSION_UNCERTAIN`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            `ACECF_DGII_REJECTED`: la DGII rechazó la aprobación comercial; el detalle va en
            `details.dgiiSubmission.dgiiMessages`. Se puede corregir y enviar otra vez.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '423':
          description: PRODUCTION_NOT_ACTIVE.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '503':
          description: >-
            `ACECF_DGII_CERTIFICATE_UNAVAILABLE`, `DIRECTORY_DGII_AUTH_FAILED`,
            `DIRECTORY_ACCESS_TOKEN_MISSING`, `DIRECTORY_FETCH_TIMEOUT`,
            `DIRECTORY_FETCH_FAILED` o `ACECF_SIGNING_FAILED`. También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/inbound-documents:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Lista los e-CF recibidos por el cliente en TesteCF (pruebas).
      description: >-
        Igual que `.../production/inbound-documents` (cursor, filtros y elementos), pero
        solo con los e-CF recibidos en TesteCF; nunca muestra los de producción. Requiere
        `documents:read`, no exige producción activa y la Cuenta fiscal debe tener TesteCF
        (si no, `404 ENVIRONMENT_NOT_FOUND`). En TesteCF el directorio de la DGII devuelve
        su emisor-receptor simulado para cualquier RNC, así que solo llegan los e-CF que le
        emite otro cliente de ZarelaFact o el mismo cliente a su propio RNC: ZarelaFact se los
        entrega en su receptor de TesteCF. También llegan como webhook `document.received`
        con `environment` `testecf`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/ReceivedDocumentsGroup'
        - $ref: '#/components/parameters/ReceivedDocumentsType'
        - $ref: '#/components/parameters/ReceivedDocumentsEncf'
        - $ref: '#/components/parameters/ReceivedDocumentsIssuerRnc'
        - $ref: '#/components/parameters/ReceivedDocumentsFrom'
        - $ref: '#/components/parameters/ReceivedDocumentsTo'
        - $ref: '#/components/parameters/ReceivedDocumentsLimit'
        - $ref: '#/components/parameters/ReceivedDocumentsCursor'
      responses:
        '200':
          description: e-CF recibidos con su estado de aprobación comercial.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerReceivedDocumentsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/inbound-documents/{inboundDocumentId}:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Consulta un e-CF recibido por el cliente en TesteCF.
      description: >-
        Igual que `.../production/inbound-documents/{inboundDocumentId}`, para un e-CF
        recibido en TesteCF. Requiere `documents:read` y no exige producción activa. Un
        documento de producción, de otra Cuenta fiscal o una ACECF responde
        `404 RECEIVED_DOCUMENT_NOT_FOUND`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/InboundDocumentId'
      responses:
        '200':
          description: e-CF recibido con su estado de aprobación comercial.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerReceivedDocumentResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/inbound-documents/{inboundDocumentId}/xml:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Descarga el XML de un e-CF recibido por el cliente en TesteCF.
      description: >-
        Igual que `.../production/inbound-documents/{inboundDocumentId}/xml`, para un e-CF
        recibido en TesteCF: los bytes del emisor, después de comprobar su huella SHA-256.
        El webhook `document.received` de TesteCF trae este enlace en `resource.xmlUrl`.
        Requiere `documents:read`. Un documento de producción o de otra Cuenta fiscal
        responde `404 RECEIVED_DOCUMENT_NOT_FOUND`; sin XML guardado,
        `404 RECEIVED_DOCUMENT_XML_NOT_AVAILABLE`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - $ref: '#/components/parameters/InboundDocumentId'
      responses:
        '200':
          description: XML del e-CF recibido.
          content:
            application/xml:
              schema: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          description: >-
            RECEIVED_DOCUMENT_XML_INTEGRITY_FAILED: la copia guardada no coincide con su huella
            SHA-256, así que no se entrega. Escríbenos con el `correlationId`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/inbound-documents/{inboundDocumentId}/commercial-approval:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Acepta o rechaza comercialmente un e-CF recibido en TesteCF (ACECF).
      description: >-
        Igual que en producción, pero en TesteCF y sin exigir producción activa: el ACECF va
        a la DGII de TesteCF y después al emisor. Si el emisor es cliente de ZarelaFact con
        TesteCF y certificado activo, se le entrega en el receptor de TesteCF de ZarelaFact
        (`commercialApproval.targetSource` `zarelafact_testecf`); a cualquier otro emisor, en
        la URL que da el directorio de la DGII de TesteCF, que es su emisor-receptor simulado.
        Requiere `documents:create`. Un e-CF recibido en producción responde `404`.
        `202` si llegó al emisor; `502` si el despacho al emisor falló o quedó incierto.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: inboundDocumentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [decision]
              properties:
                decision: { type: string, enum: [accept, reject] }
                rejectionReason: { type: string, maxLength: 250 }
      responses:
        '200':
          description: ACECF firmada y enviada (o registrada).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '202':
          description: ACECF firmada, aceptada por la DGII y entregada al emisor.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  correlationId: { type: string }
        '409':
          description: >-
            La aprobación ya se envió con otra decisión, o un envío anterior a la DGII
            quedó incierto (`ACECF_DGII_SUBMISSION_UNCERTAIN`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: >-
            `ACECF_DGII_REJECTED`: la DGII rechazó la aprobación comercial; el detalle va en
            `details.dgiiSubmission.dgiiMessages`. Se puede corregir y enviar otra vez.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '503':
          description: >-
            `ACECF_DGII_CERTIFICATE_UNAVAILABLE`, `DIRECTORY_DGII_AUTH_FAILED`,
            `DIRECTORY_ACCESS_TOKEN_MISSING`, `DIRECTORY_FETCH_TIMEOUT`,
            `DIRECTORY_FETCH_FAILED` o `ACECF_SIGNING_FAILED`. También `SERVICE_UNAVAILABLE` con `Retry-After` (ver `ServiceUnavailable`).
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /partner/v1/sandbox/documents:
    post:
      tags: [Partner, Sandbox]
      security:
        - PartnerKeyAuth: []
      summary: Prueba un documento en el Sandbox de tu Partner, sin certificado.
      description: >-
        Un solo Sandbox por Partner: lo comparten tus credenciales de prueba y de producción y
        todos tus clientes. No hace falta una Cuenta fiscal ni un certificado, y el RNC emisor
        puede ser cualquiera. Recibe el JSON DGII con `ECF` en la raíz o envuelto en `document`, igual que la emisión Partner, o el contrato simplificado, y responde como el
        Sandbox directo: el veredicto que daría la DGII, simulado, sin validez fiscal, sin
        envío a la DGII, sin cargo y sin contar para el plan; se conserva 30 días. Un e-NCF ya
        usado en tu Sandbox para el mismo RNC emisor se rechaza (DGII 1209). Requiere
        `documents:validate`.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EcfSubmitRequest' }
      responses:
        '201':
          description: Documento guardado con su veredicto simulado.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SandboxSubmitResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    get:
      tags: [Partner, Sandbox]
      security:
        - PartnerKeyAuth: []
      summary: Lista los documentos del Sandbox de tu Partner.
      description: >-
        Del más reciente al más antiguo, con `limit` y `offset`. Requiere `documents:read`.
        Un `verdict` o un `documentType` que no existen responden `400 INVALID_SANDBOX_DOCUMENTS_QUERY`; `limit` y `offset` que no son números se ignoran, y `limit` se acota entre 1 y 100.
      parameters:
        - $ref: '#/components/parameters/SandboxLimit'
        - $ref: '#/components/parameters/SandboxOffset'
        - $ref: '#/components/parameters/SandboxVerdict'
        - $ref: '#/components/parameters/SandboxDocumentType'
        - $ref: '#/components/parameters/SandboxSearch'
      responses:
        '200':
          description: Página de documentos del Sandbox.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SandboxDocumentsResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/sandbox/documents/{documentId}:
    get:
      tags: [Partner, Sandbox]
      security:
        - PartnerKeyAuth: []
      summary: Consulta un documento del Sandbox de tu Partner con sus razones.
      description: >-
        Requiere `documents:read`. Un documento de otro Partner, o un id que no existe, responde
        `404 DOCUMENT_NOT_FOUND`.
      parameters:
        - $ref: '#/components/parameters/SandboxDocumentId'
      responses:
        '200':
          description: Documento del Sandbox.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SandboxDocumentResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/sandbox/documents/{documentId}/xml:
    get:
      tags: [Partner, Sandbox]
      security:
        - PartnerKeyAuth: []
      summary: Descarga el XML simulado del documento del Sandbox de tu Partner.
      description: >-
        XML sin firma digital, con un comentario que indica que es del Sandbox y que no se envió
        a la DGII. Sin validez fiscal. Requiere `documents:read`. Responde `409
        SANDBOX_DOCUMENT_NOT_PRINTABLE` si el JSON enviado no se pudo convertir en un e-CF.
      parameters:
        - $ref: '#/components/parameters/SandboxDocumentId'
      responses:
        '200':
          description: XML simulado del e-CF, sin firma.
          content:
            application/xml:
              schema: { type: string }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/SandboxNotPrintable'
        '422':
          $ref: '#/components/responses/SandboxRenderFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/sandbox/documents/{documentId}/pdf:
    get:
      tags: [Partner, Sandbox]
      security:
        - PartnerKeyAuth: []
      summary: Descarga la representación impresa simulada del documento del Sandbox de tu Partner.
      description: >-
        PDF con la leyenda «SANDBOX ZARELAFACT — SIN VALIDEZ FISCAL», sin código de seguridad ni
        QR. Requiere `documents:read`. Responde `409 SANDBOX_DOCUMENT_NOT_PRINTABLE` como el XML.
      parameters:
        - $ref: '#/components/parameters/SandboxDocumentId'
      responses:
        '200':
          description: Representación impresa simulada, en PDF.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/SandboxNotPrintable'
        '422':
          $ref: '#/components/responses/SandboxRenderFailed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/documents:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Prevalida o emite un e-CF de prueba en TesteCF, el ambiente de pruebas de la cuenta fiscal.
      description: >-
        TesteCF es el ambiente de pruebas de la DGII para cada Cuenta fiscal: el mismo contrato que
        `POST /production/documents` (JSON DGII o simplificado, `validate=true`,
        `Prefer: wait=N`, idempotencia por eNCF), pero el e-CF va al ambiente de
        pruebas de la DGII. No exige producción activa ni plan: los comprobantes
        de prueba no cuentan en el plan ni se cobran. Firma con el certificado
        de la Cuenta fiscal (el mismo de CerteCF y eCF), así que el .p12 debe
        estar cargado. TesteCF es compartido por todos los contribuyentes: usa
        secuencias altas (por ejemplo E310009000001) para no chocar con eNCF ya
        usados. Los webhooks `document.state_changed` llegan con
        `environment: testecf`.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: validate
          in: query
          required: false
          schema: { type: boolean, default: false }
        - $ref: '#/components/parameters/PreferWait'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [document]
              properties:
                document:
                  $ref: '#/components/schemas/EcfSubmitRequest'
      responses:
        '200':
          description: Preflight válido.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '201':
          $ref: '#/components/responses/SubmitSigned'
        '202':
          description: >-
            Documento encolado. Con `Prefer: wait=N`, la DGII no respondió
            dentro del plazo y trae `Retry-After`.
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '409':
          description: ENCF_PAYLOAD_MISMATCH o ENCF_REPLAY_UNVERIFIABLE para el eNCF enviado; ENCF_NOT_IN_REGISTERED_RANGE o ENCF_RANGE_DISABLED si la Cuenta fiscal registro rangos de ese tipo y el eNCF no cae en uno vigente.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: Validación fiscal fallida; `errors` lista los campos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/documents/{documentId}:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Consulta el estado de un documento de prueba (TesteCF).
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: documentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: Estado del documento.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerDocumentStatus'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/documents/{documentId}/xml:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Descarga el XML firmado de un documento de prueba (TesteCF).
      description: Responde `409 DOCUMENT_NOT_SIGNED` mientras el documento no está firmado.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: documentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: XML firmado del e-CF.
          content:
            application/xml:
              schema: { type: string }
        '409':
          description: DOCUMENT_NOT_SIGNED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/documents/{documentId}/pdf:
    get:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Descarga la representación impresa (PDF) de un documento de prueba (TesteCF).
      description: Responde `409 DOCUMENT_NOT_SIGNED` mientras el documento no está firmado, `409 RI_AWAITING_DGII_RESPONSE` mientras la DGII no responde y `409 RI_NOT_DELIVERABLE_REJECTED` si la DGII rechazó el resumen RFCE. El emisor impreso es el de la Cuenta fiscal.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
        - name: documentId
          in: path
          required: true
          schema: { type: string, format: uuid }
      responses:
        '200':
          description: PDF tamaño carta con QR, código de seguridad y fecha de firma.
          content:
            application/pdf:
              schema: { type: string, format: binary }
        '409':
          description: DOCUMENT_NOT_SIGNED, RI_AWAITING_DGII_RESPONSE, RI_NOT_DELIVERABLE_REJECTED o RI_NOT_DELIVERABLE_NOT_TRANSMITTED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '422':
          description: RI_GENERATION_FAILED.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/testecf/documents/status/batch:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Reconcilia estados de documentos de prueba (TesteCF).
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusBatchRequest'
      responses:
        '200':
          description: Estados actuales.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/fiscal-accounts/{fiscalAccountId}/production/documents/status/batch:
    post:
      tags: [Partner, Documentos]
      security:
        - PartnerKeyAuth: []
      summary: Reconcilia estados de documentos de produccion.
      parameters:
        - $ref: '#/components/parameters/PartnerFiscalAccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusBatchRequest'
      responses:
        '200':
          description: Estados actuales.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/webhook-endpoints:
    get:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Lista webhooks del Partner.
      responses:
        '200':
          description: Endpoints configurados.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookEndpointsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Registra un endpoint webhook del ERP.
      description: La URL normalizada identifica un endpoint dentro del Partner. Repetir la creación conserva configuración y secreto; devuelve 200 sin secreto y no reactiva un endpoint pausado/deshabilitado. Un endpoint solo se filtra por eventTypes (recibe todos los clientes y ambientes). El cuerpo de cada evento (partner.webhook.v1), su firma y ejemplos están en https://zarelafact.com/docs/partners/webhooks.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerWebhookEndpointRequest'
      responses:
        '201':
          description: Endpoint creado; el secreto se muestra una sola vez.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookEndpointResponse'
        '200':
          description: Endpoint existente; replayed=true, sin signingSecret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookEndpointResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/webhook-endpoints/{endpointId}/test:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Encola una entrega webhook de prueba.
      description: |
        Crea una entrega durable `webhook.test` para una cuenta fiscal del Partner.
        La entrega se firma con el secreto vigente y la procesa el worker; nunca
        expone el secreto ni crea un evento fiscal real.
      parameters:
        - name: endpointId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerWebhookTestRequest'
      responses:
        '202':
          description: Entrega de prueba encolada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookTestResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /partner/v1/webhook-endpoints/{endpointId}/rotate-secret:
    post:
      tags: [Partner]
      security:
        - PartnerKeyAuth: []
      summary: Rota el secreto de un webhook.
      description: Durante overlapSeconds las entregas Partner llevan dos firmas v1 (actual y anterior). El receptor debe aceptar cualquiera. Una rotación activa repetida antes de vencer la ventana devuelve 409; la recuperación controlada exige pausar primero.
      parameters:
        - name: endpointId
          in: path
          required: true
          schema: { type: string, format: uuid }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                overlapSeconds: { type: integer, minimum: 1, maximum: 604800, default: 86400 }
      responses:
        '200':
          description: Endpoint actualizado; el nuevo secreto se muestra una sola vez.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerWebhookEndpointResponse'
        '409':
          description: WEBHOOK_ROTATION_IN_PROGRESS; espera a que expire la ventana o pausa para recuperación controlada.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key server-to-server del ambiente.
    PartnerKeyAuth:
      type: apiKey
      in: header
      name: X-PARTNER-KEY
      description: Credencial server-to-server del ERP/Partner. Nunca se expone al usuario final.
  parameters:
    PartnerFiscalAccountId:
      name: fiscalAccountId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Identificador de la cuenta fiscal PSFE, opaco para el ERP.
    CertificationCaseId:
      name: caseId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    CertificationRunId:
      name: runId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    DocumentReference:
      name: documentReference
      in: path
      required: true
      description: '`documentId` (UUID) o eNCF del documento, por ejemplo E310000000001.'
      schema: { type: string }
    InboundDocumentId:
      name: inboundDocumentId
      in: path
      required: true
      description: '`inboundDocumentId` del e-CF recibido (lista, webhook `document.received`).'
      schema: { type: string, format: uuid }
    IssuedDocumentsIssueDateFrom:
      name: issueDateFrom
      in: query
      required: false
      description: e-CF con `FechaEmision` desde este día (incluido), `AAAA-MM-DD`.
      schema: { type: string, format: date, examples: ['2026-09-01'] }
    IssuedDocumentsIssueDateTo:
      name: issueDateTo
      in: query
      required: false
      description: e-CF con `FechaEmision` hasta este día (incluido), `AAAA-MM-DD`.
      schema: { type: string, format: date, examples: ['2026-09-30'] }
    IssuedDocumentsType:
      name: documentType
      in: query
      required: false
      description: Tipo de e-CF, por ejemplo E31.
      schema: { type: string, pattern: '^[Ee][0-9]{2}$' }
    IssuedDocumentsStatus:
      name: status
      in: query
      required: false
      description: >-
        Estado del documento, el mismo `status` de la consulta por lote (por ejemplo
        `accepted`, `accepted_conditional`, `rejected`, `pending_dgii_status`, `signed`,
        `contingency`, `transmission_failed` o `cancelled`). `preflight_validated` no es un
        e-CF emitido y responde `400`.
      schema: { type: string, pattern: '^[a-z_]+$' }
    ReceivedCommercialApprovalId:
      name: inboundDocumentId
      in: path
      required: true
      description: '`inboundDocumentId` de la ACECF recibida (lista, webhook `document.commercial_approval_received`).'
      schema: { type: string, format: uuid }
    ReceivedCommercialApprovalsEncf:
      name: encf
      in: query
      required: false
      description: e-NCF exacto del e-CF que emitiste.
      schema: { type: string, pattern: '^[Ee][0-9]{12}$' }
    ReceivedCommercialApprovalsBuyerRnc:
      name: buyerRnc
      in: query
      required: false
      description: RNC o cédula de tu cliente (RNCComprador del ACECF).
      schema: { type: string, pattern: '^([0-9]{9}|[0-9]{11})$' }
    ReceivedDocumentsGroup:
      name: group
      in: query
      required: false
      description: Pestaña de la pantalla Recibidos del portal.
      schema:
        type: string
        enum: [por_aprobar, aceptados, rechazados, no_recibidos]
    ReceivedDocumentsType:
      name: documentType
      in: query
      required: false
      description: Tipo de e-CF, por ejemplo E31.
      schema: { type: string, pattern: '^[Ee][0-9]{2}$' }
    ReceivedDocumentsEncf:
      name: encf
      in: query
      required: false
      description: e-NCF exacto.
      schema: { type: string, pattern: '^[Ee][0-9]{12}$' }
    ReceivedDocumentsIssuerRnc:
      name: issuerRnc
      in: query
      required: false
      description: RNC o cédula del proveedor.
      schema: { type: string, pattern: '^([0-9]{9}|[0-9]{11})$' }
    ReceivedDocumentsFrom:
      name: from
      in: query
      required: false
      description: >-
        Recibidos desde este momento (incluido). `AAAA-MM-DD` es la medianoche de
        República Dominicana; también acepta fecha y hora ISO 8601.
      schema: { type: string, examples: ['2026-10-01'] }
    ReceivedDocumentsTo:
      name: to
      in: query
      required: false
      description: >-
        Recibidos antes de este momento (no incluido). `AAAA-MM-DD` es la medianoche de
        República Dominicana; también acepta fecha y hora ISO 8601.
      schema: { type: string, examples: ['2026-11-01'] }
    ReceivedDocumentsLimit:
      name: limit
      in: query
      required: false
      description: Documentos por página. Un valor mayor que 100 se trata como 100.
      schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
    ReceivedDocumentsCursor:
      name: cursor
      in: query
      required: false
      description: El `nextCursor` de la página anterior.
      schema: { type: string, maxLength: 512 }
    Environment:
      name: environment
      in: path
      required: true
      schema:
        type: string
        enum: [TesteCF, CerteCF, eCF]
      description: Ambiente DGII al que pertenece la operacion.
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 128
        pattern: '^[A-Za-z0-9._:-]+$'
      description: |
        Identificador estable requerido para enviar una ANECF. Reutilice el mismo
        valor solo con los mismos rangos; la emision normal de e-CF usa el propio eNCF.
    PreferWait:
      name: Prefer
      in: header
      required: false
      schema:
        type: string
        example: wait=10
      description: |
        RFC 7240. `wait=N` (N de 1 a 15 segundos) espera la respuesta de la DGII
        (TrackID del e-CF o respuesta del resumen RFCE) para responder `201` con
        los datos de impresion. Un N mayor cuenta como 15; un valor invalido se
        ignora y la emision responde como sin la cabecera. El plazo cuenta desde
        que llega la solicitud.
    SandboxDocumentId:
      name: documentId
      in: path
      required: true
      description: Id del documento del Sandbox, el que devuelve el `POST`.
      schema: { type: string, format: uuid }
    SandboxLimit:
      name: limit
      in: query
      required: false
      description: Documentos por página, de 1 a 100.
      schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
    SandboxOffset:
      name: offset
      in: query
      required: false
      description: Documentos que se saltan antes de la página.
      schema: { type: integer, minimum: 0, default: 0 }
    SandboxVerdict:
      name: verdict
      in: query
      required: false
      description: >-
        Filtra por veredicto. Repite el parámetro o sepáralos con comas para varios.
      schema: { type: string, enum: [accepted, accepted_conditional, rejected] }
    SandboxDocumentType:
      name: documentType
      in: query
      required: false
      description: Filtra por tipo de e-CF (E31, E32, E33, E34, E41, E43, E44, E45, E46 o E47).
      schema: { type: string, enum: [E31, E32, E33, E34, E41, E43, E44, E45, E46, E47] }
    SandboxSearch:
      name: search
      in: query
      required: false
      description: Busca en el e-NCF, el RNC y el nombre del comprador, sin distinguir mayúsculas.
      schema: { type: string }
  responses:
    BadRequest:
      description: Solicitud invalida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SandboxNotPrintable:
      description: >-
        SANDBOX_DOCUMENT_NOT_PRINTABLE: el JSON enviado no se pudo convertir en un e-CF, así
        que el documento del Sandbox no tiene XML ni PDF.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SandboxRenderFailed:
      description: >-
        SANDBOX_RENDER_FAILED (XML) o RI_GENERATION_FAILED (PDF): no se pudo generar el
        archivo del documento del Sandbox.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SandboxDailyLimit:
      description: >-
        SANDBOX_DAILY_LIMIT: tu cuenta llegó al límite diario del Sandbox (documentos guardados
        en las últimas 24 horas, válidos o rechazados). El documento no se guarda; el mensaje
        indica el límite. Los envíos de hace más de 24 horas ya no cuentan. También
        RATE_LIMIT_EXCEEDED si superas el límite de peticiones por minuto de tu clave.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: >-
        Credenciales ausentes o inválidas: la clave falta, no existe, fue revocada, venció o
        es de otro ambiente. Una caída temporal de ZarelaFact nunca responde 401: responde
        `503 SERVICE_UNAVAILABLE`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Recurso no encontrado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Scope insuficiente u operación no permitida para la credencial.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: El estado actual del recurso no admite la operación; `error.code` indica el motivo.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: Payload bien formado pero rechazado por reglas de negocio o fiscales.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: >-
        PAYMENT_REQUIRED: la emisión en producción (eCF) necesita un plan pagado.
        Solo la responde eCF; TesteCF, CerteCF y `validate=true` nunca se
        bloquean por cobro. `details.reason`: `free_tier_exhausted` (cuenta
        directa sin plan pagado que ya usó sus 50 e-CF gratis del mes),
        `payment_required` (Partner sin plan pagado; los Partners no tienen
        tramo gratis) o `payment_failed` (pago vencido y terminó la gracia de 7
        días; el propietario cambia la tarjeta en Empresa → Gestionar plan y
        el pago pendiente se cobra al guardarla). `details.billingUrl` es la
        página del plan en el portal. Además
        trae `accountType` (direct o partner), `plan`, `limit`, `used`
        (accepted + reserved), `accepted` (aceptados por la DGII en el periodo),
        `reserved` (en camino a la DGII), `graceUntil`, `periodStart`,
        `periodEnd` y `periodBasis` (`calendar_month`: mes calendario de RD, el
        del plan Gratis y los planes activados a mano). No se resuelve
        reintentando: el documento no se registra y el eNCF queda libre.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            ok: false
            error:
              code: PAYMENT_REQUIRED
              message: 'Usaste los 50 e-CF gratis del mes en producción (eCF). Para seguir emitiendo elige un plan en https://zarelafact.com/empresa#plan. TesteCF y CerteCF siguen gratis.'
              details:
                reason: free_tier_exhausted
                billingUrl: https://zarelafact.com/empresa#plan
                accountType: direct
                plan: gratis
                limit: 50
                used: 50
                accepted: 48
                reserved: 2
                graceUntil: null
                periodStart: '2026-10-01T04:00:00.000Z'
                periodEnd: '2026-11-01T04:00:00.000Z'
                periodBasis: calendar_month
    Locked:
      description: PRODUCTION_NOT_ACTIVE; la Cuenta fiscal todavía no está autorizada para producción.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SubmitSigned:
      description: >-
        Con `Prefer: wait=N`: la DGII ya respondio (TrackID del e-CF o respuesta
        Aceptado/Aceptado Condicional del resumen RFCE) o el documento quedo en
        contingencia. Misma forma que el `202`, con `effects.signed` en true,
        `effects.dgiiSubmitted` en true si la DGII lo recibio, y en `result` el
        estado actual (`status`, `dgiiStatus`, `trackId`), `securityCode`,
        `qrUrl`, `printing`, `printingStatus`, `dgiiMessages` y `lastError`,
        como la consulta. Un e-CF con TrackID todavia no es aceptado: el estado
        final llega mientras `asyncStatusRequired` sea true.
      headers:
        Preference-Applied:
          $ref: '#/components/headers/PreferenceApplied'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubmitResponse'
    TooManyRequests:
      description: >-
        RATE_LIMIT_EXCEEDED (ventana fija por IP, credencial, Partner, Cuenta fiscal
        o permiso) incluye `Retry-After`, cabeceras `X-RateLimit-*` y
        `details.retryAfterSeconds`/`details.limit`; espera ese tiempo antes de
        reintentar. En emisión, PLAN_LIMIT_EXCEEDED indica que un plan pagado
        agotó su cupo del periodo más su margen de tolerancia sin costo (30 % el
        primer periodo que se pasa, 20 % el siguiente seguido, 10 % el tercero y
        0 % después; vuelve al 30 % tras un periodo dentro del plan o al subir de
        plan; no aplica a Gratis ni a A medida): no trae `Retry-After` y no se
        resuelve reintentando. Consumen cupo los e-CF aceptados por la DGII (accepted,
        accepted_conditional) según su fecha de aceptación dentro del periodo
        del plan: el ciclo de la suscripción para un plan pagado en línea (se
        renueva el mismo día cada mes) o el mes calendario de República
        Dominicana para un plan activado a mano. Los que van en camino a la DGII
        lo reservan mientras se resuelven. Rechazados, cancelados y preflight no
        lo consumen. En un Partner el cupo suma todas sus Cuentas fiscales.
        `details`: plan, limit (el del plan), used, accepted, reserved, billingUrl,
        periodStart, periodEnd y periodBasis (subscription o calendar_month); con
        margen, además hardLimit (plan + margen), tolerancePct, toleranceStep y
        nextTolerancePct.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: >-
        SERVICE_UNAVAILABLE: ZarelaFact no puede atender en este momento (su base de datos
        o un servicio interno no responde). No es un problema de la credencial ni de la
        solicitud, y nunca se responde 401 por esta causa. Espera los segundos de
        `Retry-After` y reintenta la misma solicitud; en emisión, el mismo JSON con el
        mismo eNCF (o la misma `Idempotency-Key`): si el documento llegó a guardarse no
        se crea otro. El mensaje es siempre el mismo y no trae `details`.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            ok: false
            correlationId: ae5acff4-583c-4e30-b305-11befe8c922e
            error:
              code: SERVICE_UNAVAILABLE
              message: Servicio temporalmente no disponible. Reintente en unos segundos.
  headers:
    RetryAfter:
      description: Segundos que el cliente debe esperar antes de reintentar (mínimo 1).
      schema: { type: integer, minimum: 1 }
    PreferenceApplied:
      description: Preferencia aplicada (RFC 7240), por ejemplo `wait=10`; con un N mayor que 15, `wait=15`.
      schema: { type: string, example: wait=10 }
    RateLimitLimit:
      description: Máximo de solicitudes de la ventana que se agotó.
      schema: { type: integer }
    RateLimitRemaining:
      description: Solicitudes restantes en la ventana.
      schema: { type: integer, minimum: 0 }
    RateLimitReset:
      description: Instante Unix (segundos) en que se reinicia la ventana.
      schema: { type: integer }
  schemas:
    HealthResponse:
      type: object
      required: [ok, service, status, checkedAt]
      properties:
        ok:
          type: boolean
        service:
          type: string
          const: psfe-api
        status:
          type: string
          enum: [alive]
        checkedAt:
          type: string
          format: date-time
    ReadinessResponse:
      type: object
      required: [ok, service, status, checks]
      properties:
        ok:
          type: boolean
        service:
          type: string
        status:
          type: string
          enum: [ready, not_ready]
        checks:
          type: array
          items:
            type: object
            required: [status, name, message]
            properties:
              status:
                type: string
                enum: [pass, warn, fail]
              name:
                type: string
              message:
                type: string
              details:
                type: object
                additionalProperties: true
    EcfSubmitRequest:
      type: object
      additionalProperties: true
      description: |
        JSON DGII/XSD con raiz `ECF`, o contrato simplificado soportado por
        compatibilidad. Para emitir debe incluir el eNCF asignado por el POS;
        solo el preflight `validate=true` puede omitirlo.

        `FechaVencimientoSecuencia` (JSON DGII, `DD-MM-YYYY`) o
        `sequenceExpirationDate` (contrato simplificado) es obligatoria para
        E31, E33, E41, E43, E44, E45, E46 y E47 y no aplica a E32/E34.

        En el contrato simplificado solo se admiten las propiedades listadas aqui
        (mas `idempotencyKey`); cualquier otra responde `422` con
        `details.code = UNKNOWN_FIELD`. Un campo que el XSD del tipo no tiene
        (por ejemplo `paymentTerms` en E34/E43 o descuentos en E43/E47) tambien
        responde `422`.

        El contrato simplificado no asume datos fiscales; si faltan responde `422`
        con el campo: `issueDate` (todos los tipos), `paymentType` (todos los tipos
        tienen TipoPago), `incomeType` (E31, E32, E33, E34, E44, E45 y E46), por
        linea `itbisRate` o `indicadorFacturacion` (salvo E43, E44, E46 y E47, cuyo
        indicador fija la DGII) e `itemKind` (salvo E47, siempre servicio),
        `issuer.address` (del perfil de la cuenta o del payload; nunca "N/A") y
        `reference.reason` en E33/E34.

        Los nodos opcionales del XSD (`purchaseOrderNumber`, `purchaseOrderDate`,
        `internalInvoiceNumber`, `internalOrderNumber`, `sellerCode`, `buyer.contact`,
        `buyer.email`, `buyer.internalCode`, `delivery`, `transport` y
        `lines[].description`) se validan con el largo y el patron del XSD del tipo;
        si el XSD del tipo no tiene el nodo responde `422` en el campo.
      properties:
        type:
          type: string
          description: Tipo e-CF del contrato simplificado (`E31`..`E47`).
        encf:
          type: string
          pattern: '^E\d{12}$'
          description: eNCF asignado por el POS/ERP (E + tipo de 2 digitos + secuencia de 10).
        issueDate:
          type: string
          description: Fecha de emision (fecha o fecha-hora ISO, o `DD-MM-AAAA`). Obligatoria en el contrato simplificado.
        issuer:
          type: object
          description: >-
            Emisor. Lo que falte se completa con el perfil de la cuenta; el RNC debe ser el
            de la cuenta. La direccion es obligatoria: si el perfil no la tiene, `address`
            debe venir aqui (si no, `422` en `issuer.address`).
          properties:
            rnc: { type: string }
            legalName: { type: string, maxLength: 150 }
            commercialName: { type: string, maxLength: 150 }
            branch: { type: string, maxLength: 20, description: 'Sucursal. Solo va en el e-CF si se envia; no hay valor por omision.' }
            address: { type: string, maxLength: 100 }
            email: { type: string, maxLength: 80 }
            phone:
              oneOf:
                - { type: string, pattern: '^\d{3}-\d{3}-\d{4}$' }
                - { type: array, maxItems: 3, items: { type: string, pattern: '^\d{3}-\d{3}-\d{4}$' } }
              description: >-
                Telefonos del emisor (`TablaTelefonoEmisor`, hasta 3, formato
                `809-555-1234`). Otro formato responde `422` (`details.code =
                ISSUER_PHONE_INVALID`). El PDF no los imprime.
            province: { type: string, description: Codigo de provincia de la Tabla III DGII. }
            municipality: { type: string, description: Codigo de municipio de la Tabla III DGII. }
        buyer:
          type: object
          description: |
            Comprador. `rnc` admite guiones y espacios y se envia solo con digitos
            (9 u 11); solo se valida la estructura. Con `foreignId` se omite el RNC;
            `foreignId` no existe en E31/E41/E45. E43 no lleva comprador. Una E32 de
            RD$250,000 o mas, y las notas que la modifican, requieren `rnc` o
            `foreignId`.
          properties:
            rnc: { type: string }
            foreignId: { type: string, maxLength: 20 }
            name: { type: string, maxLength: 150 }
            address: { type: string, maxLength: 100 }
            contact:
              type: string
              maxLength: 80
              description: ContactoComprador. No existe en E43/E47.
            email:
              type: string
              maxLength: 80
              description: CorreoComprador (CorreoValidationType del XSD; sin `_`). No existe en E43/E47.
            internalCode:
              type: string
              maxLength: 20
              description: CodigoInternoComprador. No existe en E43/E47.
        paymentType:
          type: string
          enum: [cash, card, credit, free]
          description: |
            `cash` contado (TipoPago 1); `card` contado con tarjeta (TipoPago 1 y
            FormaPago 3); `credit` credito (TipoPago 2); `free` entrega gratuita
            (TipoPago 3). Obligatorio en el contrato simplificado.
        dueDate:
          type: string
          description: FechaLimitePago. Solo con `credit`. Si es anterior a `issueDate`, se emite con el aviso `PAYMENT_DUE_DATE_BEFORE_ISSUE` (la DGII lo deja Aceptado Condicional); no existe en E43.
        paymentTerms:
          type: string
          maxLength: 15
          description: TerminoPago (letras, numeros o espacios). No existe en E34/E43.
        incomeType:
          type: string
          enum: ['01', '02', '03', '04', '05', '06']
          description: TipoIngresos. Obligatorio en E31, E32, E33, E34, E44, E45 y E46; no existe en E41/E43/E47.
        deferredSend:
          type: boolean
          description: |
            `true` solo si la DGII autorizo el envio diferido (Decreto 587-24 art.
            39): emite `IndicadorEnvioDiferido` 1 y el PDF lleva la leyenda. Si la
            cuenta tiene la autorizacion registrada se asume `true`; `false` lo
            quita. Sin la autorizacion registrada responde `422` (`details.code =
            DEFERRED_SEND_NOT_AUTHORIZED`), tambien con `IndicadorEnvioDiferido` 1
            en JSON DGII. No existe en E41/E43/E47.
        currency:
          type: string
          enum: [DOP, BRL, CAD, CHF, CHY, XDR, DKK, EUR, GBP, JPY, NOK, SCP, SEK, USD, VEF, HTG, MXN, COP]
          description: |
            Moneda de los montos (Tabla II DGII). Distinta de DOP: los montos se
            convierten a pesos con `exchangeRate` y el e-CF lleva `OtraMoneda` y
            `OtraMonedaDetalle`.
        exchangeRate:
          type: number
          exclusiveMinimum: 0
          maximum: 999.9999
          description: Pesos por unidad de `currency`, hasta 4 decimales. Obligatorio con `currency` distinta de DOP.
        zeroTaxMode:
          type: string
          enum: [exempt, taxedZero]
          description: Con `itbisRate` 0, exento (indicador 4) o gravado a 0 % (indicador 3).
        documentTaxTotal:
          type: number
          description: ITBIS total que declara el documento. No sustituye `itbisRate` ni `indicadorFacturacion` en las lineas.
        globalDiscountAmount:
          type: number
          description: Descuento global en monto. No se combina con `globalDiscountPercent`; no existe en E43/E47.
        globalDiscountPercent:
          type: number
          minimum: 0
          maximum: 100
          description: Descuento global en porcentaje (2 decimales). Con varias tasas se declara en `%`.
        globalSurchargeAmount:
          type: number
          minimum: 0
          description: |
            Recargo global en monto (DescuentosORecargos con `TipoAjuste` R): se
            suma a la base de cada tasa. No se combina con
            `globalSurchargePercent`; no existe en E43/E47. Con
            `pricesIncludeTax` responde `422`
            (`GLOBAL_AMOUNT_WITH_PRICES_INCLUDE_TAX`): usa el porcentaje.
        globalSurchargePercent:
          type: number
          minimum: 0
          maximum: 100
          description: Recargo global en porcentaje de la suma de las lineas (2 decimales). Con varias tasas se declara en `%`.
        pricesIncludeTax:
          type: boolean
          description: |
            `true` si los precios y montos de las lineas incluyen el ITBIS: emite
            `IndicadorMontoGravado` 1 y calcula como la DGII: base de cada tasa =
            suma de sus `MontoItem` / (1 + tasa), redondeo medio-arriba a 2
            decimales; ITBIS = base x tasa; `MontoTotal` = bases + exento + ITBIS
            (puede diferir un centavo de la suma de los precios). Descuento y
            recargo globales solo en porcentaje. Sin el campo, o `false`, los
            precios no incluyen el ITBIS (`IndicadorMontoGravado` 0). Solo existe en
            E31, E32, E33, E34, E41 y E45.
        purchaseOrderNumber:
          type: string
          maxLength: 20
          description: Comprador/NumeroOrdenCompra. No existe en E41/E43/E47.
        purchaseOrderDate:
          type: string
          pattern: '^(\d{1,2}-\d{1,2}-\d{4}|\d{4}-\d{2}-\d{2})$'
          description: Comprador/FechaOrdenCompra (`DD-MM-YYYY` o `YYYY-MM-DD`, fecha real). No existe en E41/E43/E47.
        internalInvoiceNumber:
          type: string
          maxLength: 20
          description: Emisor/NumeroFacturaInterna.
        internalOrderNumber:
          type: string
          pattern: '^\d{1,20}$'
          description: Emisor/NumeroPedidoInterno (solo digitos).
        sellerCode:
          type: string
          maxLength: 60
          description: Emisor/CodigoVendedor. No existe en E41/E43/E47.
        delivery:
          type: object
          additionalProperties: false
          description: Datos de entrega del comprador. No existen en E41/E43/E47.
          properties:
            date:
              type: string
              pattern: '^(\d{1,2}-\d{1,2}-\d{4}|\d{4}-\d{2}-\d{2})$'
              description: Comprador/FechaEntrega (`DD-MM-YYYY` o `YYYY-MM-DD`, fecha real).
            contact: { type: string, maxLength: 100, description: Comprador/ContactoEntrega. }
            address: { type: string, maxLength: 100, description: Comprador/DireccionEntrega. }
        transport:
          type: object
          additionalProperties: false
          description: Seccion `Transporte` (transporte local). No existe en E41/E43; en E47 solo tiene PaisDestino.
          properties:
            driver: { type: string, maxLength: 20, description: Conductor. }
            document: { type: string, pattern: '^\d{1,20}$', description: DocumentoTransporte (solo digitos). }
            vehicleNumber: { type: string, maxLength: 10, description: Ficha. }
            plate: { type: string, maxLength: 7, description: Placa. }
            route: { type: string, maxLength: 20, description: RutaTransporte. }
            zone: { type: string, maxLength: 20, description: ZonaTransporte. }
            deliveryNoteNumber: { type: string, maxLength: 20, description: NumeroAlbaran. }
        lines:
          type: array
          maxItems: 10000
          description: Lineas de detalle. Maximo segun el XSD del tipo (1000; 10000 en E33/E34).
          items:
            type: object
            required: [name, quantity, unitPrice]
            properties:
              name: { type: string, maxLength: 80 }
              description:
                type: string
                maxLength: 1000
                description: DescripcionItem. El PDF imprime hasta 200 caracteres; el XML la lleva completa.
              quantity: { type: number, exclusiveMinimum: 0, description: Hasta 2 decimales. }
              unitPrice: { type: number, minimum: 0, description: Hasta 4 decimales. Con `pricesIncludeTax` incluye el ITBIS. }
              itbisRate: { type: number, enum: [0, 16, 18], description: 'Obligatorio, o `indicadorFacturacion`, salvo en E43, E44, E46 y E47.' }
              indicadorFacturacion: { type: integer, enum: [1, 2, 3, 4], description: Debe coincidir con `itbisRate` si van los dos. }
              unitMeasure: { type: integer, minimum: 1, maximum: 62, description: Codigo de la Tabla IV DGII. }
              itemKind: { type: string, enum: [good, service], description: Obligatorio salvo en E47 (siempre servicio). }
              discountAmount: { type: number, minimum: 0 }
              discountPercent: { type: number, minimum: 0, maximum: 100 }
              retention:
                type: object
                description: Solo E41/E47. En E47 `isrAmount` es obligatorio en cada linea.
                properties:
                  agentIndicator: { type: integer, enum: [1, 2] }
                  itbisAmount: { type: number, minimum: 0 }
                  isrAmount: { type: number, minimum: 0 }
        reference:
          type: object
          description: >-
            Solo notas E33/E34: `encf`, `date` y `reason` son obligatorios; en E34 tambien
            `modificationCode` (1, 2 o 3). En E33 solo 3 (por omision 3). En otro tipo
            responde 422. `modificationCode` 4 (reemplazo de un comprobante de papel serie B
            emitido en contingencia) responde 422 con `details.code`
            `CONTINGENCY_PAPER_REPLACEMENT_UNSUPPORTED` en cualquier tipo: si la DGII no
            responde, el e-CF se emite igual y queda en contingencia electronica.
          properties:
            encf:
              type: string
              pattern: '^([Bb]\d{10}|[Ee]\d{12}|[AaPp]\d{18})$'
              description: NCFModificado, serie B de 11 posiciones, eNCF de 13 o serie A o P de 19.
            date: { type: string }
            modificationCode: { type: integer, enum: [1, 2, 3] }
            reason: { type: string, maxLength: 90 }
        sequenceExpirationDate:
          type: string
          pattern: '^(\d{1,2}-\d{1,2}-\d{4}|\d{4}-\d{2}-\d{2})$'
          description: |
            Contrato simplificado: fecha de vencimiento del rango de eNCF autorizado
            por DGII (`DD-MM-YYYY` o `YYYY-MM-DD`, fecha real). Obligatoria para
            E31, E33, E41, E43, E44, E45, E46 y E47. No existe en E32/E34: si se
            envia, se omite con un aviso (`SEQUENCE_EXPIRATION_DATE_NOT_APPLICABLE`). ZarelaFact no
            usa valor por omision: si falta o es invalida responde `422`. Tambien `422` si es
            anterior a `issueDate` (`SEQUENCE_EXPIRED_AT_ISSUE_DATE`) o distinta del vencimiento
            del rango registrado que contiene el eNCF (`SEQUENCE_EXPIRATION_RANGE_MISMATCH`).
          examples: ['31-12-2028']
      allOf:
        - if:
            required: [type]
            properties:
              type:
                enum: [E31, E33, E41, E43, E44, E45, E46, E47]
          then:
            required: [sequenceExpirationDate]
        - if:
            required: [type]
          then:
            required: [issueDate, paymentType, lines]
        - if:
            required: [type]
            properties:
              type:
                enum: [E31, E32, E33, E34, E44, E45, E46]
          then:
            required: [incomeType]
        - if:
            required: [type]
            properties:
              type:
                not:
                  enum: [E43, E44, E46, E47]
          then:
            properties:
              lines:
                items:
                  anyOf:
                    - required: [itbisRate]
                    - required: [indicadorFacturacion]
        - if:
            required: [type]
            properties:
              type:
                not:
                  const: E47
          then:
            properties:
              lines:
                items:
                  required: [itemKind]
        - if:
            required: [type]
            properties:
              type:
                enum: [E33, E34]
          then:
            required: [reference]
            properties:
              reference:
                required: [encf, date, reason]
        - if:
            required: [type]
            properties:
              type:
                const: E34
          then:
            properties:
              reference:
                required: [modificationCode]
    SubmitResponse:
      type: object
      required: [ok, correlationId]
      properties:
        ok:
          type: boolean
        correlationId:
          type: string
        mode:
          type: string
          enum: [preflight, queued, idempotent, submit_validation]
        errors:
          type: array
          description: Errores de validacion (`field`, `message`, `severity`, `details`); presente cuando `ok=false`.
          items:
            type: object
            additionalProperties: true
            properties:
              field: { type: string }
              message: { type: string }
              severity: { type: string }
        warnings:
          type: array
          description: >-
            Avisos que no impiden la emisión, con `field`, `message`, `severity` y
            `details.code`. En producción, `PLAN_LIMIT_OVERAGE` dice que el e-CF entró
            pasado el plan, dentro del margen de tolerancia sin costo, y
            `PLAN_LIMIT_NEAR` que el periodo no tiene margen y el consumo pasó el 90 %
            del plan. Ambos traen en `details` plan, limit, hardLimit, tolerancePct,
            used, marginRemaining, state, nextTolerancePct, periodStart, periodEnd y
            billingUrl: muéstrale al usuario que suba de plan.
          items:
            type: object
            additionalProperties: true
        result:
          type: object
          additionalProperties: true
          properties:
            documentId:
              type: string
            encf:
              type: string
            status:
              type: string
            asyncStatusRequired:
              type: boolean
            securityCode:
              type: [string, 'null']
              description: Null en el `202`; en el `201` de `Prefer` con `wait=N`, el código de seguridad.
            qrUrl:
              type: [string, 'null']
              description: Null en el `202`; en el `201` de `Prefer` con `wait=N`, la URL del QR.
            printing:
              $ref: '#/components/schemas/DocumentPrinting'
            printingStatus:
              $ref: '#/components/schemas/PrintingStatus'
            contingency:
              $ref: '#/components/schemas/DocumentContingency'
            dgiiMessages:
              $ref: '#/components/schemas/DgiiMessages'
            lastError:
              $ref: '#/components/schemas/DocumentLastError'
            replacesDocumentId:
              type: string
              description: >-
                Solo al reenviar con el mismo eNCF (corregido o con el mismo JSON) un e-CF que
                la DGII rechazo con `secuenciaUtilizada: false` (eCF y TesteCF): el
                `documentId` del rechazado, que se conserva intacto como evidencia. Va con
                el aviso `ENCF_REISSUED_AFTER_REJECTION`.
        preflight:
          type: object
          additionalProperties: true
        dgiiPrediction:
          description: >-
            Predicción orientativa del veredicto de la DGII (solo en ?validate=true). No cambia ok ni el código HTTP: la DGII tiene la última palabra.
          allOf:
            - $ref: '#/components/schemas/SandboxVerdict'
    StatusBatchRequest:
      type: object
      properties:
        documentIds:
          type: array
          maxItems: 100
          items:
            type: string
        encfs:
          type: array
          maxItems: 100
          items:
            type: string
      anyOf:
        - required: [documentIds]
        - required: [encfs]
    StatusBatchResponse:
      type: object
      required: [ok, environment, correlationId, count, results]
      properties:
        ok:
          type: boolean
        environment:
          type: string
        correlationId:
          type: string
        count:
          type: integer
        results:
          type: array
          items:
            type: object
            additionalProperties: true
            properties:
              documentId: { type: [string, 'null'] }
              encf: { type: [string, 'null'] }
              status:
                type: string
                description: >-
                  Estado en ZarelaFact (`queued_for_signing`, `signed`,
                  `rfce_pending_dispatch`, `sent`, `pending_dgii_status`, `accepted`,
                  `accepted_conditional`, `rejected`, `contingency`, `transmission_failed`,
                  `cancelled`) o `not_found`. `transmission_failed`: el envío a la DGII falló
                  de forma definitiva (o no hay certificado activo) y no se reintenta solo;
                  no es final.
              dgiiStatus: { type: [string, 'null'] }
              trackId: { type: [string, 'null'] }
              lastCheckedAt: { type: [string, 'null'] }
              printing:
                $ref: '#/components/schemas/DocumentPrinting'
              printingStatus:
                $ref: '#/components/schemas/PrintingStatus'
              contingency:
                $ref: '#/components/schemas/DocumentContingency'
              dgiiMessages:
                $ref: '#/components/schemas/DgiiMessages'
              lastError:
                $ref: '#/components/schemas/DocumentLastError'
              sequenceUsed:
                $ref: '#/components/schemas/DocumentSequenceUsed'
              receiverDelivery:
                $ref: '#/components/schemas/ReceiverDelivery'
              errors:
                type: array
                description: >-
                  `NOT_FOUND` si el documento no existe en el ambiente; si no, el mismo
                  error de `lastError` (`code` y `message`). Vacío cuando no hay error.
                items:
                  type: object
                  required: [code]
                  properties:
                    code: { type: string }
                    message: { type: [string, 'null'] }
    ReceiverDelivery:
      type: [object, 'null']
      description: >-
        Entrega del e-CF al receptor electrónico (B2B), después de que la DGII lo acepta.
        Null si el documento no tuvo entrega (todavía o nunca). `state`: `submitting`
        (enviándose), `retry_scheduled` (falló por una causa pasajera; se reintenta solo en
        `nextAttemptAt`, hasta 5 intentos), `sent` (el receptor lo recibió), `failed`
        (falló de forma definitiva o se agotaron los intentos), `uncertain` (el receptor no
        respondió; se concilia con `POST /{environment}/documentos-ecf/{documentId}/entrega-receptor/reconciliar`),
        `dispatch_failed` (conciliado como no entregado), `not_electronic` (el comprador no
        es receptor electrónico: se le entrega la representación impresa) o `not_applicable`.
      required: [state, attempts, lastAttemptAt, nextAttemptAt, sentAt, reason, lastError]
      properties:
        state:
          type: string
          enum: [submitting, retry_scheduled, sent, failed, uncertain, dispatch_failed, not_electronic, not_applicable]
        attempts: { type: integer, minimum: 0 }
        lastAttemptAt: { type: [string, 'null'], format: date-time }
        nextAttemptAt: { type: [string, 'null'], format: date-time }
        sentAt: { type: [string, 'null'], format: date-time }
        reason:
          type: [string, 'null']
          description: Por qué no aplica (solo en `not_electronic` y `not_applicable`).
        lastError:
          type: [object, 'null']
          description: El último fallo (en `retry_scheduled`, `failed`, `uncertain` y `dispatch_failed`).
          properties:
            code: { type: [string, 'null'] }
            message: { type: [string, 'null'] }
            statusCode: { type: [integer, 'null'] }
            codigoMotivoNoRecibido:
              type: [integer, string, 'null']
              description: Motivo del ARECF «no recibido» del receptor, si lo hubo.
    DocumentLastError:
      type: [object, 'null']
      description: >-
        Por qué el documento no avanza: el último fallo de envío a la DGII o, en
        contingencia, la caída de la DGII (`DGII_UNAVAILABLE`). Null sin error, con estado
        final (`accepted`, `accepted_conditional`, `rejected`) o `cancelled`. Se borra
        cuando un envío posterior sale bien. Lo traen la consulta por lote y el webhook
        `document.state_changed`. En `transmission_failed` (el envío falló de forma
        definitiva o no hay certificado activo) trae `retrying: false`.
      required: [code]
      properties:
        code:
          type: string
          description: >-
            Código estable, por ejemplo `DGII_CERTIFICATE_NOT_DELEGATED` (el certificado
            no está delegado para el RNC emisor; los envíos de la cuenta quedan en pausa y
            se reintentan cada 30 min), `DGII_RECEPTION_REJECTED` (la DGII respondió que
            no recibió el documento, con su motivo en `dgiiMessages`),
            `DGII_RFCE_DUPLICATE_UNRESOLVED`, `XSD_VALIDATION_FAILED`,
            `CERTIFICATE_NOT_CONFIGURED` o `CERTIFICATE_EXPIRED` (sin certificado activo o
            vigente: `transmission_failed`) o `DGII_UNAVAILABLE` (contingencia; una
            autenticación DGII caída, `DGII_AUTH_UNAVAILABLE`, cuenta como caída).
        message: { type: [string, 'null'] }
        dgiiMessages:
          type: array
          items: { type: string }
        hint:
          type: string
          description: >-
            Qué hacer, cuando aplica. Con `DGII_CERTIFICATE_NOT_DELEGATED`: el
            administrador del contribuyente debe delegar el rol «Firmante Autorizado» al
            titular del certificado en la Oficina Virtual de la DGII («Delegación de
            e-CF» → «Delegación de Roles»).
        retrying:
          type: boolean
          description: >-
            Si ZarelaFact lo sigue intentando solo. `false` solo en `transmission_failed`:
            la DGII no tiene el documento y hace falta corregir la causa y reenviarlo (el
            mismo XML firmado, sin firmar otra vez) o anular su eNCF con una ANECF.
        at:
          type: [string, 'null']
          format: date-time
    ContingencyResponse:
      type: object
      required: [ok, environment, mode, count, documents]
      properties:
        ok:
          type: boolean
        environment:
          type: string
        mode:
          type: string
          const: contingency
        dgiiService:
          type: object
          description: >-
            Si la DGII responde en este ambiente. `degraded` desde que un envío o una
            consulta entró en contingencia (DGII sin respuesta, timeout, 5xx, autenticación
            DGII caída o circuit breaker abierto) hasta la siguiente respuesta de la DGII.
            Cada cambio también llega como webhook `dgii.service_degraded` o
            `dgii.service_restored`.
          required: [state]
          properties:
            state:
              type: string
              enum: [available, degraded]
            since:
              type: [string, 'null']
              format: date-time
            code:
              type: [string, 'null']
              description: Código de la caída, por ejemplo `DGII_TIMEOUT` o `DGII_CIRCUIT_OPEN`.
            dgiiEnvironment:
              type: [string, 'null']
            processing:
              type: object
              description: >-
                Si la DGII está lenta en este ambiente: responde, pero deja los e-CF
                «En Proceso» mucho más de lo normal (2 e-CF distintos esperando más de
                5 minutos en la última media hora, o uno solo más de 15). Vuelve a
                `normal` con media hora sin ninguno esperando más de 5 minutos. Cada
                cambio también llega como webhook `dgii.service_slow` o
                `dgii.service_slow_cleared`.
              required: [state]
              properties:
                state:
                  type: string
                  enum: [normal, slow]
                since:
                  type: [string, 'null']
                  format: date-time
        count:
          type: integer
        documents:
          type: array
          items:
            type: object
            additionalProperties: true
    CreateSequenceRangeRequest:
      type: object
      required: [ecfType, start, end]
      properties:
        ecfType:
          type: string
          example: E31
        start:
          type: integer
        end:
          type: integer
        expiresAt:
          type: string
          description: >-
            Vencimiento del rango autorizado por la DGII: fecha-hora ISO, o solo la
            fecha (`AAAA-MM-DD` o `DD-MM-AAAA`), que vence al final de ese dia en
            hora de RD (23:59:59 GMT-4). Si el rango tiene vencimiento, la emision de
            un eNCF del rango exige que `FechaVencimientoSecuencia` sea ese dia.
          examples: ['2028-12-31', '2028-12-31T23:59:59-04:00']
    SequenceRangeResponse:
      type: object
      required: [ok, range]
      properties:
        ok:
          type: boolean
        range:
          type: object
          additionalProperties: true
    SequenceRangesResponse:
      type: object
      required: [ok, ranges]
      properties:
        ok:
          type: boolean
        ranges:
          type: array
          items:
            type: object
            additionalProperties: true
    AnnulmentRequest:
      type: object
      required: [cancellations]
      properties:
        rncEmisor:
          type: string
        annulmentDate:
          type: string
          format: date-time
        submit:
          type: boolean
          default: true
        cancellations:
          type: array
          minItems: 1
          items:
            type: object
            required: [ecfType, sequences]
            properties:
              ecfType:
                type: string
                example: E31
              sequences:
                type: array
                minItems: 1
                items:
                  type: object
                  required: [from]
                  properties:
                    from:
                      type: string
                      example: E310000000150
                    to:
                      type: string
                      example: E310000000160
    CommercialApprovalRequest:
      type: object
      required: [decision]
      properties:
        decision:
          type: string
          enum: [accept, reject]
        rejectionReason:
          type: string
        approvalDate:
          type: string
          description: >-
            Fecha y hora de la decisión (FechaHoraAprobacionComercial). Sin zona es hora de
            República Dominicana; con `Z` u offset se convierte a hora de RD. Debe estar
            entre la medianoche de la `FechaEmision` del e-CF recibido y la hora actual de
            RD más 5 minutos; fuera de ese rango responde `422 COMMERCIAL_APPROVAL_DATE_INVALID`.
            Si no se envía, es la hora actual de RD.
          examples: ['2026-10-20T15:30:00']
        targetUrl:
          type: string
          format: uri
          description: >-
            URL de aprobación comercial del emisor. Solo se usa si el emisor no está en el
            directorio DGII del ambiente (`DIRECTORY_VENDOR_NOT_FOUND`) o en CerteCF; si
            está, debe ser su URL registrada. No evita la consulta al directorio, aunque
            `autoResolveDirectory` sea `false`.
        dispatch:
          oneOf:
            - type: boolean
            - type: string
              enum: [build-only]
        autoResolveDirectory:
          type: boolean
    ReceivedDocumentView:
      type: object
      description: >-
        Lo mismo que muestra la pantalla Recibidos del portal. Proveedor, tipo, monto y
        fecha de emisión salen del XML recibido.
      required: [kind, documentType, senderName, senderRnc, amount, issueDate, acuse, approval, group]
      properties:
        kind:
          type: string
          enum: [recepcion]
        documentType:
          type: [string, 'null']
          examples: [E31]
        senderName:
          type: [string, 'null']
          description: RazonSocialEmisor.
        senderRnc:
          type: [string, 'null']
        amount:
          type: [string, 'null']
          description: MontoTotal, como viene en el XML.
        issueDate:
          type: [string, 'null']
          format: date
          description: FechaEmision del e-CF.
        acuse:
          type: object
          required: [state]
          properties:
            state:
              type: string
              enum: [recibido, no_recibido]
            motivo:
              type: [integer, 'null']
              description: CodigoMotivoNoRecibido (1 especificación, 2 firma, 3 duplicado, 4 RNC comprador).
            motivoLabel:
              type: [string, 'null']
        approval:
          type: object
          required: [state]
          properties:
            state:
              type: string
              enum: [pendiente, aceptado, rechazado, no_aplica]
            deadline:
              type: [string, 'null']
              format: date
              description: Solo en `pendiente`; igual a `commercialApprovalDeadline`.
            warning:
              type: string
              description: El envío de tu ACECF no se confirmó.
            by:
              type: string
              enum: [ti]
            acecfSent:
              type: boolean
            reason:
              type: [string, 'null']
        group:
          type: [string, 'null']
          enum: [por_aprobar, aceptados, rechazados, no_recibidos, null]
        dgii:
          type: [object, 'null']
          description: >-
            Validez del e-CF en la DGII (Consulta Estado). `null` si el acuse fue «no
            recibido». `no_aplica` en CerteCF (no tiene Consulta Estado).
          required: [state]
          properties:
            state:
              type: string
              enum: [por_consultar, en_proceso, aceptado, aceptado_condicional, rechazado, no_encontrado, no_aplica, no_verificado]
            checkedAt:
              type: [string, 'null']
              format: date-time
            dgiiStatus:
              type: [string, 'null']
            retrying:
              type: boolean
              description: Si ZarelaFact volverá a consultarlo.
            reason:
              type: string
    ReceivedDocumentDgiiValidity:
      type: [object, 'null']
      description: >-
        Validez del e-CF recibido en la DGII según Consulta Estado, consultada por
        ZarelaFact con el token DGII de tu cuenta poco después de recibirlo. `null`
        mientras no se ha consultado. «No encontrado» y una DGII caída se reintentan con
        espera creciente (hasta 6 consultas en ~31 h); después queda final.
      required: [state, final]
      properties:
        state:
          type: string
          enum: [pending, accepted, accepted_conditional, rejected, not_found, not_applicable, unverified]
          description: >-
            `not_applicable`: el ambiente no tiene Consulta Estado (CerteCF).
            `unverified`: se agotaron las consultas sin respuesta concluyente.
        final:
          type: boolean
        dgiiStatus:
          type: [string, 'null']
          description: El `estado` que respondió la DGII.
        checkedAt:
          type: [string, 'null']
          format: date-time
        attempts:
          type: integer
        reason:
          type: string
    ReceivedDocument:
      type: object
      required:
        - inboundDocumentId
        - encf
        - issuerRnc
        - receiverRnc
        - status
        - commercialApproval
        - receivedAt
        - group
        - commercialApprovalDeadline
        - view
      properties:
        inboundDocumentId:
          type: string
          format: uuid
        encf:
          type: [string, 'null']
        issuerRnc:
          type: [string, 'null']
        receiverRnc:
          type: [string, 'null']
        status:
          type: string
          enum: [received, duplicate, rejected]
          description: '`duplicate` o `rejected`: el acuse (ARECF) dijo «no recibido».'
        commercialApproval:
          type: [object, 'null']
          additionalProperties: true
          description: Tu ACECF (estado, decisión, XML y entrega) si ya respondiste.
        dgiiValidity:
          $ref: '#/components/schemas/ReceivedDocumentDgiiValidity'
        receivedAt:
          type: string
          format: date-time
        group:
          type: [string, 'null']
          enum: [por_aprobar, aceptados, rechazados, no_recibidos, null]
        commercialApprovalDeadline:
          type: [string, 'null']
          format: date
          description: >-
            Fecha límite para responder la aprobación comercial: el día 15 del mes
            siguiente a la FechaEmision del e-CF (D587-24 art. 17 párr. V y Formato 606,
            NG 07-18 art. 8). Solo en `por_aprobar`; `null` en los demás grupos o si el
            XML no trae FechaEmision.
          examples: ['2026-11-15']
        view:
          $ref: '#/components/schemas/ReceivedDocumentView'
    ReceivedDocumentsResponse:
      type: object
      required: [ok, environment, items, nextCursor]
      properties:
        ok:
          type: boolean
        environment:
          type: string
        items:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/ReceivedDocument'
        nextCursor:
          type: [string, 'null']
          description: Cursor de la página siguiente; `null` en la última.
        correlationId:
          type: string
    ReceivedDocumentResponse:
      allOf:
        - $ref: '#/components/schemas/ReceivedDocument'
        - type: object
          required: [ok, environment]
          properties:
            ok:
              type: boolean
            environment:
              type: string
            correlationId:
              type: string
    IssuedDocument:
      type: object
      required:
        - documentId
        - encf
        - documentType
        - issueDate
        - buyerRnc
        - buyerName
        - total
        - status
        - dgiiStatus
        - trackId
        - createdAt
        - sentAt
        - acceptedAt
        - rejectedAt
        - printing
        - dgiiMessages
      properties:
        documentId:
          type: string
          format: uuid
        encf:
          type: [string, 'null']
        documentType:
          type: [string, 'null']
          examples: [E31]
        issueDate:
          type: [string, 'null']
          format: date
          description: FechaEmision del e-CF (`AAAA-MM-DD`).
        buyerRnc:
          type: [string, 'null']
          description: >-
            RNCComprador del e-CF. `null` si el comprador no tiene RNC (consumidor
            final, E43) o se identificó con `IdentificadorExtranjero` (E47 o
            comprador extranjero): ese identificador no es un RNC y no va aquí.
        buyerName:
          type: [string, 'null']
        total:
          type: [string, 'null']
          description: MontoTotal del e-CF.
        status:
          type: string
          description: Estado del documento, como en la consulta por lote.
        dgiiStatus:
          type: [string, 'null']
        trackId:
          type: [string, 'null']
        createdAt:
          type: string
          format: date-time
          description: Cuándo lo recibió ZarelaFact.
        sentAt:
          type: [string, 'null']
          format: date-time
        acceptedAt:
          type: [string, 'null']
          format: date-time
        rejectedAt:
          type: [string, 'null']
          format: date-time
        printing:
          $ref: '#/components/schemas/DocumentPrinting'
        printingStatus:
          $ref: '#/components/schemas/PrintingStatus'
        contingency:
          $ref: '#/components/schemas/DocumentContingency'
        dgiiMessages:
          $ref: '#/components/schemas/DgiiMessages'
    IssuedDocumentsResponse:
      type: object
      required: [ok, environment, items, nextCursor]
      properties:
        ok:
          type: boolean
        environment:
          type: string
        items:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/IssuedDocument'
        nextCursor:
          type: [string, 'null']
          description: Cursor de la página siguiente; `null` en la última.
        correlationId:
          type: string
    ReceivedCommercialApproval:
      type: object
      required:
        - inboundDocumentId
        - encf
        - documentId
        - issuerRnc
        - buyerRnc
        - status
        - decision
        - rejectionReason
        - approvalDateTime
        - issueDate
        - amount
        - notReceived
        - receivedAt
      properties:
        inboundDocumentId:
          type: string
          format: uuid
        encf:
          type: [string, 'null']
          description: e-NCF del e-CF que emitiste.
        documentId:
          type: [string, 'null']
          format: uuid
          description: Tu e-CF emitido con ese e-NCF en el mismo ambiente; `null` si no está entre tus emitidos.
        issuerRnc:
          type: [string, 'null']
          description: RNCEmisor del ACECF (tu RNC).
        buyerRnc:
          type: [string, 'null']
          description: RNCComprador del ACECF (tu cliente, quien aprueba o rechaza).
        status:
          type: string
          enum: [received, duplicate, rejected]
          description: '`duplicate` o `rejected`: el receptor no la recibió (ver `notReceived`).'
        decision:
          type: [string, 'null']
          enum: [accepted, rejected, null]
          description: Estado del ACECF (1 aceptado, 2 rechazado); `null` si no se recibió.
        rejectionReason:
          type: [string, 'null']
          description: DetalleMotivoRechazo, solo con `decision` `rejected`.
        approvalDateTime:
          type: [string, 'null']
          description: FechaHoraAprobacionComercial tal como viene en el ACECF (DD-MM-AAAA HH:mm:ss, hora de RD).
          examples: ['25-10-2026 11:15:00']
        issueDate:
          type: [string, 'null']
          format: date
          description: FechaEmision del e-CF según el ACECF.
        amount:
          type: [string, 'null']
          description: MontoTotal del e-CF según el ACECF.
        correspondence:
          type: [object, 'null']
          description: >-
            Si el ACECF corresponde con el e-CF que emitiste, marcado al recibirlo: `matched`
            (mismo RNC emisor, RNC comprador y monto), `mismatch` (`mismatches` dice qué campo
            difiere: valor recibido y el de tu e-CF) o `ecf_not_found` (no emitiste ese e-NCF en
            el ambiente). `null` si no se recibió o es anterior a esta marca. Llega igual en el
            webhook `document.commercial_approval_received` (`data.correspondence`).
          required: [status, documentId, mismatches]
          properties:
            status:
              type: string
              enum: [matched, mismatch, ecf_not_found]
            documentId:
              type: [string, 'null']
            mismatches:
              type: array
              items:
                type: object
                required: [field, received, expected]
                properties:
                  field: { type: string, enum: [RNCEmisor, RNCComprador, MontoTotal] }
                  received: { type: [string, 'null'] }
                  expected: { type: [string, 'null'] }
        notReceived:
          type: [object, 'null']
          description: Motivo por el que el receptor no la recibió (1 especificación, 2 firma, 3 duplicado, 4 RNC comprador).
          properties:
            motivo:
              type: [integer, 'null']
            motivoLabel:
              type: [string, 'null']
        receivedAt:
          type: string
          format: date-time
    ReceivedCommercialApprovalsResponse:
      type: object
      required: [ok, environment, items, nextCursor]
      properties:
        ok:
          type: boolean
        environment:
          type: string
        items:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/ReceivedCommercialApproval'
        nextCursor:
          type: [string, 'null']
          description: Cursor de la página siguiente; `null` en la última.
        correlationId:
          type: string
    ReceivedCommercialApprovalResponse:
      allOf:
        - $ref: '#/components/schemas/ReceivedCommercialApproval'
        - type: object
          required: [ok, environment]
          properties:
            ok:
              type: boolean
            environment:
              type: string
            correlationId:
              type: string
    PartnerReceivedDocumentsResponse:
      type: object
      required: [fiscalAccountId, items, nextCursor]
      properties:
        fiscalAccountId:
          type: string
          format: uuid
        items:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/ReceivedDocument'
        nextCursor:
          type: [string, 'null']
          description: Cursor de la página siguiente; `null` en la última.
        correlationId:
          type: string
    PartnerReceivedDocumentResponse:
      description: El mismo elemento de la lista (ReceivedDocument), más `fiscalAccountId`.
      type: object
      required: [fiscalAccountId]
      properties:
        fiscalAccountId:
          type: string
          format: uuid
        correlationId:
          type: string
      allOf:
        - $ref: '#/components/schemas/ReceivedDocument'
    CommercialApprovalStatusResponse:
      type: object
      required: [ok, inboundId, encf, issuerRnc, receiverRnc]
      properties:
        ok:
          type: boolean
        inboundId:
          type: string
        encf:
          type: string
        issuerRnc:
          type: string
        receiverRnc:
          type: string
        commercialApproval:
          type:
            - object
            - 'null'
          additionalProperties: true
    CommercialApprovalSubmitResponse:
      type: object
      required: [ok, inboundId, encf, commercialApproval]
      properties:
        ok:
          type: boolean
        inboundId:
          type: string
        encf:
          type: string
        commercialApproval:
          type: object
          additionalProperties: true
    FiscalReconciliationRequest:
      type: object
      additionalProperties: false
      required: [outcome, evidence]
      properties:
        outcome:
          type: string
          description: Resultado confirmado externamente; el conjunto válido depende del recurso.
          enum: [accepted, rejected, sent, dispatch_failed]
        evidence:
          $ref: '#/components/schemas/FiscalReconciliationEvidence'
    FiscalReconciliationEvidence:
      type: object
      additionalProperties: false
      required: [source, reference, observedAt]
      properties:
        source:
          type: string
          maxLength: 80
          example: dgii-status-query
        reference:
          type: string
          maxLength: 256
          example: track-or-ticket-reference
        observedAt:
          type: string
          format: date-time
        arecfXml:
          type: string
          description: ARECF firmado obligatorio cuando una entrega al receptor se reconcilia como `sent`; se valida contra ARECF v1.0 y la identidad del documento.
        details:
          type: object
          additionalProperties: true
    ReconciliationResponse:
      type: object
      required: [ok, idempotent]
      properties:
        ok:
          type: boolean
          const: true
        idempotent:
          type: boolean
        annulment:
          type: object
          additionalProperties: true
        commercialApproval:
          type: object
          additionalProperties: true
    CertificationSetRequest:
      type: object
      description: |
        Set a enviar. Las pruebas de datos usan el Excel que la DGII le entregó al
        contribuyente: `workbookBase64` (tal cual), `rows` o `documents`. La simulación
        usa `dgiiModel: true`. No combine los dos.
      properties:
        dgiiModel:
          type: boolean
          description: >-
            `true` envía la simulación: el set modelo de ZarelaFact (25 e-CF de todos los
            tipos y 4 resúmenes de facturas de consumo) a nombre del RNC de la cuenta, con
            un bloque de e-NCF nuevos (`summary.mode: simulation`). Solo después de que la
            DGII acepte las aprobaciones comerciales; antes responde 409
            CERTIFICATION_OWN_SET_REQUIRED, porque la DGII compara las pruebas de datos con
            el set que le entregó al contribuyente. Requiere un certificado activo.
        documents:
          type: array
          items:
            type: object
            additionalProperties: true
        rows:
          type: array
          items:
            type: object
            additionalProperties: true
        workbookBase64:
          type: string
          contentEncoding: base64
        b2bSimulation:
          type: boolean
          description: >-
            Simula la aprobación comercial (ACECF) al terminar los lotes. Por omisión es
            `true` en las pruebas de datos y `false` con `dgiiModel`.
      anyOf:
        - required: [dgiiModel]
        - required: [documents]
        - required: [rows]
        - required: [workbookBase64]
    CertificationRunResponse:
      type: object
      required: [ok, environment, mode, run]
      properties:
        ok:
          type: boolean
          const: true
        environment:
          type: string
        mode:
          type: string
          const: certification_run_started
        run:
          type: object
          required: [runId, jobId, documentIds, batches]
          additionalProperties: true
        correlationId:
          type: string
    CertificationStatusResponse:
      type: object
      required: [ok, environment, status]
      properties:
        ok:
          type: boolean
          const: true
        environment:
          type: string
        status:
          type: object
          required: [runId, jobStatus, runStatus]
          additionalProperties: true
        correlationId:
          type: string
    CertificationPartSummary:
      type: object
      required: [documentCount, accepted, rejected, inFlight, completed]
      properties:
        documentCount:
          type: integer
          description: Comprobantes activos de la parte (sin los reemplazados ni los cancelados).
        accepted: { type: integer }
        rejected: { type: integer }
        inFlight: { type: integer }
        ecf:
          description: e-CF de la parte (sin los resúmenes), como el contador «e-CF» de CerteCF.
          type: object
          properties:
            total: { type: integer }
            accepted: { type: integer }
        summaries:
          description: Resúmenes de facturas de consumo (RFCE), como el contador «RFCE» de CerteCF.
          type: object
          properties:
            total: { type: integer }
            accepted: { type: integer }
        completed:
          type: boolean
          description: true si un run de esa parte tiene todos sus comprobantes aceptados.
    CertificationParts:
      type: object
      required: [data, simulation]
      properties:
        data: { $ref: '#/components/schemas/CertificationPartSummary' }
        simulation: { $ref: '#/components/schemas/CertificationPartSummary' }
    CertificationRestart:
      type: object
      required: [part, supersededDocumentCount, cancelledRunIds]
      properties:
        part: { type: string, enum: [data, simulation] }
        supersededDocumentCount:
          type: integer
          description: Comprobantes que quedaron reemplazados.
        cancelledRunIds:
          type: array
          items: { type: string, format: uuid }
    CertificationRestartResponse:
      type: object
      required: [ok, environment, restart, parts]
      properties:
        ok:
          type: boolean
          const: true
        environment:
          type: string
        restart: { $ref: '#/components/schemas/CertificationRestart' }
        parts: { $ref: '#/components/schemas/CertificationParts' }
        correlationId:
          type: string
    CertificationResend:
      type: object
      required: [documentId, encf, status, jobType, jobId]
      properties:
        documentId: { type: string, format: uuid }
        encf: { type: string }
        status:
          type: string
          description: Estado del comprobante al pedir el reenvío.
        jobType:
          type: string
          enum: [ecf.send, ecf.status.poll]
          description: '`ecf.status.poll` si la DGII ya le dio TrackID.'
        jobId: { type: [string, 'null'], format: uuid }
    CertificationResendResponse:
      type: object
      required: [ok, environment, resend]
      properties:
        ok:
          type: boolean
          const: true
        environment:
          type: string
        resend: { $ref: '#/components/schemas/CertificationResend' }
        correlationId:
          type: string
    CertificationEvidenceResponse:
      type: object
      required: [ok, runId, fileName, contentType, encoding, byteLength, content]
      properties:
        ok:
          type: boolean
          const: true
        runId:
          type: string
        fileName:
          type: string
        contentType:
          type: string
          const: application/zip
        encoding:
          type: string
          const: base64
        byteLength:
          type: integer
        fileCount:
          type: integer
        sha256:
          type: string
        content:
          type: string
          contentEncoding: base64
    PartnerCertificationEvidenceResponse:
      type: object
      required: [runId, fileName, contentType, encoding, byteLength, fileCount, sha256, content]
      properties:
        runId: { type: string }
        fileName: { type: string }
        contentType: { type: string, const: application/zip }
        encoding: { type: string, const: base64 }
        byteLength: { type: integer, minimum: 0 }
        fileCount: { type: integer, minimum: 0 }
        sha256: { type: string }
        content: { type: string, contentEncoding: base64 }
        correlationId: { type: string }
    PartnerDocumentStatus:
      type: object
      required: [documentId, encf, documentType, status, dgiiStatus, trackId, correlationId, createdAt, updatedAt]
      properties:
        documentId: { type: string, format: uuid }
        environment:
          type: string
          enum: [ecf, testecf]
          description: Ambiente del documento. `testecf` es el ambiente de pruebas de la Cuenta fiscal.
        encf: { type: string }
        documentType: { type: string }
        status: { type: string }
        dgiiStatus: { type: [string, 'null'] }
        trackId: { type: [string, 'null'] }
        correlationId: { type: [string, 'null'] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        lastError:
          $ref: '#/components/schemas/DocumentLastError'
        sequenceUsed:
          $ref: '#/components/schemas/DocumentSequenceUsed'
        printing:
          $ref: '#/components/schemas/DocumentPrinting'
        printingStatus:
          $ref: '#/components/schemas/PrintingStatus'
        contingency:
          $ref: '#/components/schemas/DocumentContingency'
        dgiiMessages:
          $ref: '#/components/schemas/DgiiMessages'
        receiverDelivery:
          $ref: '#/components/schemas/ReceiverDelivery'
    DocumentSequenceUsed:
      type: [boolean, 'null']
      description: >-
        Solo en la API Partner (detalle del documento, cada resultado de status/batch y
        `resource` del webhook `document.state_changed`). En un rechazo de la DGII, lo que
        respondió en `secuenciaUtilizada`, también para un resumen RFCE rechazado (E32 de
        menos de RD$250,000). `false`: se puede reenviar con el mismo eNCF, corregido o con
        el mismo JSON (`202` con `result.replacesDocumentId`). `true`: el eNCF quedo usado; otro JSON
        con ese eNCF responde `409 ENCF_PAYLOAD_MISMATCH`. `null`: el documento no esta
        rechazado o la DGII no mando el dato (se trata como usado).
    PrintingStatus:
      type: string
      enum: [awaiting_signature, awaiting_dgii, available, rejected]
      description: >-
        En qué punto está la representación impresa. `awaiting_signature`: sin firmar.
        `awaiting_dgii`: firmado, esperando la respuesta de la DGII (también en
        `transmission_failed`, hasta que un reenvío llegue a la DGII). `available`: `printing`
        trae los datos. `rejected`: la DGII rechazó el resumen RFCE (o el e-CF sin TrackID)
        y la representación impresa no se entrega.
    DocumentPrinting:
      type: [object, 'null']
      description: >-
        Datos para imprimir la representación impresa. Es null hasta que la DGII responde
        (Informe Técnico e-CF v1.0, secciones 8 y 9.1): el TrackID del e-CF o, en una
        factura de consumo menor a RD$250,000, la respuesta Aceptado o Aceptado Condicional
        del resumen RFCE. En contingencia o envío diferido autorizado aparece desde la firma,
        para imprimir con su leyenda.
      required: [securityCode, signatureDate, qrUrl, legends]
      properties:
        securityCode:
          type: string
          description: Código de seguridad de 6 caracteres derivado de la firma.
        signatureDate:
          type: [string, 'null']
          description: Fecha y hora de la firma (FechaHoraFirma, DD-MM-YYYY HH:mm:ss).
        qrUrl:
          type: [string, 'null']
          format: uri
          description: URL de verificación de la DGII que se imprime como código QR, sin modificarla.
        legends:
          type: array
          description: >-
            Las leyendas que lleva el PDF de ZarelaFact, en el orden en que se imprimen, con su
            texto literal. Si imprimes en tu propio formato, imprímelas tal cual. `contingency`:
            el envío del e-CF a la DGII se difirió por contingencia (Decreto 587-24, art. 40);
            se mantiene aunque después la DGII lo acepte. `deferred`: envío diferido autorizado
            (`IndicadorEnvioDiferido` = 1). `rejected`: la DGII rechazó el e-CF; esa
            representación impresa no sustenta crédito fiscal. Vacío si no lleva ninguna.
          items:
            type: object
            required: [key, text]
            properties:
              key:
                type: string
                enum: [contingency, deferred, rejected]
              text:
                type: string
                description: Texto literal de la leyenda.
        pdfUrl:
          type: [string, 'null']
          format: uri
          description: >-
            Solo en los webhooks `document.state_changed`: la descarga del PDF por API
            (`GET /{ambiente}/documentos-ecf/{documentId}/pdf` con X-API-KEY, o la ruta
            `.../documents/{documentId}/pdf` de la API Partner con X-PARTNER-KEY). Null en
            CerteCF por la API Partner.
    DocumentContingency:
      type: [object, 'null']
      description: >-
        Dato permanente: el envío del e-CF a la DGII se difirió por contingencia, así que se
        emitió en contingencia y su representación impresa lleva la leyenda de contingencia.
        Se mantiene aunque después la DGII lo acepte. Null si el envío nunca se difirió. Un
        documento con TrackID que pasa a `contingency` porque la DGII no responde la consulta
        de su estado no se emitió en contingencia: sigue en null.
      required: [startedAt]
      properties:
        startedAt:
          type: string
          format: date-time
          description: Cuándo se difirió el envío a la DGII por primera vez.
    DgiiMessages:
      type: array
      description: Mensajes de la respuesta final de la DGII (motivos de rechazo u observaciones). Vacío mientras no hay respuesta final.
      items: { type: string }
    PartnerProvisionRequest:
      type: object
      required: [rnc, legalName]
      additionalProperties: false
      properties:
        rnc:
          type: string
          pattern: '^[0-9]{9,11}$'
        replacesFiscalAccountId:
          type: string
          format: uuid
          description: >-
            Solo para cambiar el RNC antes de produccion: el `fiscalAccountId` actual de
            este externalTenantId. Confirma que esa cuenta se libera.
        legalName:
          type: string
          maxLength: 300
        commercialName:
          type: string
          maxLength: 300
        fiscalEmail:
          type: string
          format: email
          maxLength: 254
        phone:
          type: string
          maxLength: 50
        address:
          type: string
          maxLength: 500
        provinceCode:
          type: string
          maxLength: 20
        municipalityCode:
          type: string
          maxLength: 20
        ecfTypes:
          type: array
          maxItems: 50
          items: { type: string, maxLength: 20 }
    PartnerProfilePatch:
      type: object
      minProperties: 1
      additionalProperties: false
      properties:
        legalName: { type: string, maxLength: 300 }
        commercialName: { type: string, maxLength: 300 }
        fiscalEmail: { type: string, format: email, maxLength: 254 }
        phone: { type: string, maxLength: 50 }
        address: { type: string, maxLength: 500 }
        provinceCode: { type: string, maxLength: 20 }
        municipalityCode: { type: string, maxLength: 20 }
        ecfTypes: { type: array, maxItems: 50, items: { type: string, maxLength: 20 } }
        printedRepresentationEmail:
          type: object
          minProperties: 1
          additionalProperties: false
          description: >-
            Activa (`true`) o desactiva (`false`) por ambiente el envío de la representación
            impresa al comprador por correo. Está desactivado por defecto. Al activarlo aplica
            a los e-CF emitidos desde ese momento; el correo sale cuando la DGII acepta el e-CF
            (Aceptado o Aceptado Condicional) y el XML trae `CorreoComprador`. Solo en el perfil:
            el alta de la Cuenta fiscal no lo acepta.
          properties:
            production: { type: boolean }
            testecf: { type: boolean }
    PartnerFiscalAccountReleaseResponse:
      type: object
      required: [fiscalAccountId, externalTenantId, status, unlinkedAt]
      properties:
        fiscalAccountId: { type: string, format: uuid }
        externalTenantId: { type: string }
        status: { type: string, enum: [unlinked] }
        unlinkedAt: { type: string, format: date-time }
        correlationId: { type: string }
    PartnerAccountResponse:
      type: object
      required: [fiscalAccountId, externalTenantId, status, environments, certification]
      properties:
        fiscalAccountId: { type: string, format: uuid }
        replacedFiscalAccountId:
          type: string
          format: uuid
          description: >-
            Solo en la respuesta del PUT que cambio el RNC: la Cuenta fiscal anterior, que
            quedo liberada.
        externalTenantId: { type: string }
        rnc: { type: string }
        legalName: { type: string }
        commercialName: { type: string }
        status: { type: string }
        ownership:
          type: object
          description: >-
            Titularidad del vínculo. Se verifica al instalar un certificado válido del RNC.
            Mientras no esté verificada, otro Partner puede reclamar el RNC después de claimExpiresAt.
          required: [verified, verifiedAt, claimExpiresAt]
          properties:
            verified: { type: boolean }
            verifiedAt: { type: [string, 'null'], format: date-time }
            claimExpiresAt: { type: [string, 'null'], format: date-time }
        environments:
          type: object
          properties:
            certecf: { type: string, enum: [active, inactive] }
            ecf: { type: string, enum: [active, inactive] }
        printedRepresentationEmail:
          type: object
          description: Envío de la representación impresa al comprador por correo, por ambiente.
          properties:
            production: { $ref: '#/components/schemas/PrintedRepresentationEmailSetting' }
            testecf: { $ref: '#/components/schemas/PrintedRepresentationEmailSetting' }
        certification:
          anyOf:
            - $ref: '#/components/schemas/PartnerCertificationSummary'
            - $ref: '#/components/schemas/PartnerCertificationCase'
        correlationId: { type: string }
    PrintedRepresentationEmailSetting:
      type: object
      required: [enabled, enabledAt]
      properties:
        enabled: { type: boolean }
        enabledAt:
          type: [string, 'null']
          format: date-time
          description: Desde cuándo está activo; se envían los e-CF emitidos a partir de ese momento.

    PartnerCertificationSummary:
      type: object
      description: Estado inicial antes de crear el Caso durable.
      required: [state, checklist, nextAction]
      properties:
        state: { type: string, enum: [profile_ready, certificate_ready] }
        nextAction: { type: string, enum: [upload_certificate, create_certification_case] }
        checklist:
          type: object
          required: [certificateUploaded, runnerCompleted, dgiiApproved]
          properties:
            certificateUploaded: { type: boolean }
            runnerCompleted: { type: boolean }
            dgiiApproved: { type: boolean }
    PartnerUploadSession:
      type: object
      required: [uploadId, uploadUrl, uploadToken, expiresAt, maxBytes, browserOrigin, allowedExtensions]
      properties:
        uploadId: { type: string, format: uuid }
        uploadUrl: { type: string, format: uri }
        uploadToken: { type: string }
        expiresAt: { type: string, format: date-time }
        maxBytes: { type: integer }
        browserOrigin:
          type: [string, 'null']
          format: uri
          description: Origen de navegador autorizado para esta sesión; null solo en compatibilidad legada.
        allowedExtensions:
          type: array
          items: { type: string }
        correlationId: { type: string }
    PartnerCertificateResponse:
      type: object
      required: [certificate]
      properties:
        certificate:
          oneOf:
            - type: 'null'
            - type: object
              required: [status]
              properties:
                id:
                  type: string
                  description: Presente en `GET .../certificate`; la respuesta de carga no lo incluye.
                fingerprint: { type: string }
                rnc:
                  type: string
                  description: RNC de la Cuenta fiscal; presente en la respuesta de `PUT /certificate-upload-sessions/{uploadId}`.
                subject: { type: [string, 'null'] }
                issuer: { type: [string, 'null'] }
                serialNumber: { type: [string, 'null'] }
                validFrom: { type: string, format: date-time }
                expiresAt: { type: string, format: date-time }
                status: { type: string }
        correlationId: { type: string }
    PartnerDgiiRegistrationEnvironment:
      type: object
      required: [dgiiPortalUrl, receptionUrl, commercialApprovalUrl, authenticationUrl]
      properties:
        dgiiPortalUrl: { type: string, format: uri }
        receptionUrl: { type: string, format: uri }
        commercialApprovalUrl: { type: string, format: uri }
        authenticationUrl:
          type: string
          description: Siempre vacía; el campo se deja en blanco en DGII.
    PartnerDgiiRegistration:
      type: object
      required: [fiscalAccountId, externalTenantId, taxpayer, software, provider, environments]
      properties:
        fiscalAccountId: { type: string, format: uuid }
        externalTenantId: { type: string }
        taxpayer:
          type: object
          required: [rnc, legalName, commercialName]
          properties:
            rnc: { type: string }
            legalName: { type: string }
            commercialName: { type: [string, 'null'] }
        software:
          type: object
          required: [type, name, version]
          properties:
            type: { type: string, enum: [EXTERNO] }
            name: { type: string }
            version: { type: string }
        provider:
          type: object
          required: [rnc, rncDisplay, legalName, commercialName, email]
          properties:
            rnc: { type: string, pattern: '^[0-9]{9}$' }
            rncDisplay: { type: string }
            legalName: { type: string }
            commercialName: { type: string }
            email: { type: string, format: email }
        environments:
          type: object
          required: [certecf, ecf]
          properties:
            certecf:
              $ref: '#/components/schemas/PartnerDgiiRegistrationEnvironment'
            ecf:
              $ref: '#/components/schemas/PartnerDgiiRegistrationEnvironment'
        correlationId: { type: string }
    PartnerCertificationXmlSignature:
      type: object
      required: [documentType, rootTag, fileName, signedXmlBase64, certificate, signedAt]
      properties:
        documentType: { type: string, enum: [postulation, sworn_declaration] }
        rootTag: { type: string }
        fileName: { type: string }
        signedXmlBase64: { type: string, contentEncoding: base64 }
        certificate:
          type: object
          required: [id, fingerprint]
          properties:
            id: { type: [string, 'null'] }
            fingerprint: { type: [string, 'null'] }
        signedAt: { type: string, format: date-time }
        correlationId: { type: string }
    CommunicationTestTraffic:
      type: object
      required: [received, rejected, lastAt, rejections]
      properties:
        received: { type: integer, description: Documentos recibidos (acuse con Estado 0 o aprobación con 200). }
        rejected: { type: integer, description: Documentos no recibidos (firma o formato inválidos). }
        lastAt: { type: [string, 'null'], format: date-time }
        rejections:
          type: array
          description: Hasta 10 de los no recibidos, del más reciente al más antiguo.
          items:
            type: object
            properties:
              encf: { type: [string, 'null'] }
              issuerRnc: { type: [string, 'null'] }
              code: { type: [string, 'null'], example: INBOUND_SIGNATURE_INVALID }
              receivedAt: { type: [string, 'null'], format: date-time }
    CommercialApprovalTests:
      type: object
      description: >-
        Un envío de las aprobaciones comerciales de prueba (paso 3 de CerteCF): una por cada fila
        del Excel de la DGII, enviadas de una en una.
      required: [jobId, status, summary, approvals]
      properties:
        jobId: { type: string, format: uuid }
        status: { type: string, enum: [running, completed, failed, cancelled] }
        buyerRnc: { type: [string, 'null'] }
        startedAt: { type: [string, 'null'], format: date-time }
        completedAt: { type: [string, 'null'], format: date-time }
        summary:
          type: object
          required: [total, accepted, rejected, uncertain, errors, pending]
          properties:
            total: { type: integer }
            accepted: { type: integer }
            rejected: { type: integer }
            uncertain: { type: integer, description: Enviadas sin respuesta de la DGII. }
            errors: { type: integer, description: La DGII no las procesó (autenticación o límite de solicitudes). }
            pending: { type: integer }
        approvals:
          type: array
          items:
            type: object
            required: [encf, status]
            properties:
              encf: { type: string, example: E310000000002 }
              rncEmisor: { type: string, example: '{{RNC_PROVEEDOR}}' }
              fechaEmision: { type: string, example: 01-04-2020 }
              montoTotal: { type: string, example: '4674.35' }
              estado: { type: integer, enum: [1, 2], description: 1 aprobada, 2 rechazada. }
              status: { type: string, enum: [pending, sending, accepted, rejected, uncertain, error] }
              fechaHoraAprobacionComercial: { type: [string, 'null'], example: 03-10-2026 00:21:30 }
              sentAt: { type: [string, 'null'], format: date-time }
              messages: { type: array, items: { type: string } }
        error:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                code: { type: string }
                message: { type: string }
    PartnerCertificationCase:
      type: object
      required: [caseId, fiscalAccountId, state, checklist, nextAction]
      properties:
        caseId: { type: string, format: uuid }
        fiscalAccountId: { type: string, format: uuid }
        officialSetRef: { type: string }
        state: { type: string }
        internalState: { type: string }
        version: { type: integer }
        progress: { type: integer, minimum: 0, maximum: 100 }
        checklist:
          type: object
          required: [certificateUploaded, runnerCompleted, dgiiApproved]
          properties:
            certificateUploaded: { type: boolean }
            runnerCompleted: { type: boolean }
            dgiiApproved: { type: boolean }
            dgiiPostulationSubmitted: { type: boolean }
            printedRepresentationsUploaded: { type: boolean }
            productionUrlsSubmitted: { type: boolean }
            swornDeclarationSubmitted: { type: boolean }
            ofvRolesConfigured: { type: boolean }
            commercialApprovalsSent:
              type: boolean
              description: El último envío de las aprobaciones comerciales de prueba terminó con todas aceptadas.
            simulationPassed:
              type: boolean
              description: >-
                El último run es la simulación y la DGII la aceptó. Vuelve a false si la
                simulación se reinicia después (POST .../restart con part simulation).
                También es true si la DGII rechazó un reenvío de la simulación porque ya
                había cerrado ese paso (latestRun.dgiiPhaseClosed): sigue valiendo la
                simulación aceptada anterior, y downloads es de ese run.
        latestRun:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PartnerRunSummary'
        blockingReasons:
          type: array
          items: { type: string }
        nextAction:
          type: string
          description: >-
            El siguiente paso, en el orden del asistente: upload_certificate,
            submit_dgii_postulation, wait_for_dgii_application, upload_certification_test_set
            (el Caso usa `dgii-model`: sube el Excel de la DGII y cambia el Caso a ese set),
            run_certification_tests,
            wait_for_dgii_results, restart_failed_part, send_commercial_approvals,
            run_simulation_tests,
            upload_printed_representations,
            submit_production_urls, submit_sworn_declaration, configure_ofv_roles,
            wait_for_dgii_approval o follow_case_instructions.
        partnerActions:
          type: array
          items: { type: string }
        attestations:
          type: array
          items: { type: object, additionalProperties: true }
        downloads:
          description: >-
            Cuando la DGII aceptó el último run: las rutas para descargar el XML íntegro (e-CF) de
            las Facturas de Consumo menores a RD$250,000 (lo que se sube en «Facturas de consumo <
            250Mil»), una copia de sus resúmenes RFCE, los PDF impresos y la evidencia. Null
            mientras el run no pase.
          oneOf:
            - type: 'null'
            - type: object
              required: [runId, evidence]
              properties:
                runId: { type: string, format: uuid }
                consumerSummaries:
                  type: [string, 'null']
                  description: Copia de los resúmenes RFCE enviados de las Facturas de Consumo menores a RD$250,000 (no se suben en el portal). Null si el set no tiene.
                consumerInvoices:
                  type: [string, 'null']
                  description: XML íntegro (e-CF) de esas mismas facturas, lo que se sube en «Facturas de consumo < 250Mil». Null si el set no tiene.
                consumerInvoiceFiles:
                  type: [array, 'null']
                  description: >-
                    Una entrada por Factura de Consumo menor a RD$250,000 aceptada, con la ruta de su
                    XML suelto (`consumerInvoices` con `?encf=`), para mostrar un botón por factura. Solo
                    en el detalle de la Cuenta fiscal y del caso; no viene en los listados. Null si el set
                    no tiene.
                  items:
                    type: object
                    required: [encf, url]
                    properties:
                      encf: { type: string, example: E320000000012 }
                      url: { type: string }
                printedPdfs:
                  type: [string, 'null']
                  description: >-
                    PDF impresos de los comprobantes del run, lo que la DGII pide en el paso 5. Solo
                    cuando el último run es la simulación; null para las pruebas de datos.
                evidence: { type: string }
        commercialApprovals:
          description: >-
            El último envío de las aprobaciones comerciales de prueba (paso 3 de CerteCF). Solo en
            el detalle de la Cuenta fiscal y del Caso; null si todavía no hay ninguno.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/CommercialApprovalTests'
        communicationTests:
          description: >-
            Pruebas de comunicación (pasos 7 a 11 de CerteCF): lo que la DGII envió de verdad al
            receptor de CerteCF de la Cuenta fiscal. `ecf` son los e-CF (paso 9) y `approvals` las
            aprobaciones comerciales (paso 11). El resultado de cada prueba lo da la DGII en su
            portal. Solo en el detalle de la Cuenta fiscal y del Caso.
          type: [object, 'null']
          properties:
            ecf: { $ref: '#/components/schemas/CommunicationTestTraffic' }
            approvals: { $ref: '#/components/schemas/CommunicationTestTraffic' }
        parts:
          $ref: '#/components/schemas/CertificationParts'
          description: >-
            Avance de las pruebas de datos y de la simulación. Viene al consultar la Cuenta
            fiscal o el Caso y al reiniciar una parte.
        restart:
          $ref: '#/components/schemas/CertificationRestart'
          description: Solo al reiniciar una parte.
        closed:
          type: boolean
          description: true si el Caso se cerró para empezar con un set nuevo.
        closedAt: { type: [string, 'null'], format: date-time }
        replayed:
          type: boolean
          description: Solo en el cierre; true si el Caso ya estaba cerrado.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        correlationId: { type: string }
    PartnerCertificationTestSet:
      type: object
      required: [testSetRef, sha256, format, documentCount]
      properties:
        testSetRef:
          type: string
          pattern: '^set-[0-9a-f]{16}$'
          description: Úsalo como `officialSetRef` al crear el Caso.
        sha256: { type: string, pattern: '^[0-9a-f]{64}$' }
        format: { type: string, enum: [json, xlsx] }
        fileName: { type: [string, 'null'] }
        documentCount: { type: integer, minimum: 1 }
        types:
          type: array
          items: { type: string }
        encfs:
          type: array
          items: { type: string }
        createdAt: { type: string, format: date-time }
        replayed: { type: boolean }
        correlationId: { type: string }
    PartnerPrintedPdfsResponse:
      type: object
      required: [runId, fileName, contentType, encoding, byteLength, fileCount, exceedsDgiiLimit, content]
      properties:
        runId: { type: string, format: uuid }
        fileName: { type: string, example: 'representaciones-impresas-{{RNC}}.zip' }
        contentType: { type: string, const: application/zip }
        encoding: { type: string, const: base64 }
        byteLength: { type: integer }
        fileCount: { type: integer, minimum: 1 }
        missing:
          type: integer
          description: Comprobantes del run sin PDF todavía.
        exceedsDgiiLimit:
          type: boolean
          description: true si el ZIP pasa de 10 MB, el máximo del portal de la DGII.
        selection: { type: string, enum: [all, dgii] }
        slots:
          type: array
          description: Con selection=dgii, cada casilla del paso 5 con el e-NCF y el archivo que le toca (null si falta).
          items:
            type: object
            properties:
              slot: { type: string, example: E31 }
              label: { type: string, example: Tipo 31 }
              encf: { type: [string, 'null'] }
              fileName: { type: [string, 'null'], example: 01 - Tipo 31 - E310009002001.pdf }
        content: { type: string, contentEncoding: base64 }
        correlationId: { type: string }
    PartnerRfceSummaryXmlResponse:
      type: object
      required: [runId, fileName, contentType, encoding, fileCount, files, content]
      properties:
        runId: { type: string, format: uuid }
        encf:
          type: string
          description: Solo con `encf`, la factura descargada.
        fileName: { type: string, example: 'resumenes-rfce-{{RNC}}.zip' }
        contentType: { type: string, enum: [application/zip, application/xml] }
        encoding: { type: string, const: base64 }
        byteLength: { type: integer }
        fileCount: { type: integer, minimum: 1 }
        files:
          type: array
          description: Nombre de cada RFCE dentro del ZIP (RNC emisor + e-NCF).
          items: { type: string, example: '{{RNC}}E320000000011.xml' }
        content: { type: string, contentEncoding: base64 }
        correlationId: { type: string }
    PartnerCertificationResend:
      type: object
      required: [caseId, documentId, encf, status, jobType, jobId]
      properties:
        caseId: { type: string, format: uuid }
        documentId: { type: string, format: uuid }
        encf: { type: string }
        status:
          type: string
          description: Estado del comprobante al pedir el reenvío.
        jobType:
          type: string
          enum: [ecf.send, ecf.status.poll]
          description: '`ecf.status.poll` si la DGII ya le dio TrackID.'
        jobId: { type: [string, 'null'], format: uuid }
        correlationId: { type: string }
    PartnerRunStarted:
      type: object
      required: [caseId, runId, status, documentCount]
      properties:
        caseId: { type: string, format: uuid }
        runId: { type: string, format: uuid }
        status: { type: string, enum: [queued, running, succeeded, failed, cancelled] }
        documentCount: { type: integer }
        replayed: { type: boolean }
        correlationId: { type: string }
    PartnerRunSummary:
      type: object
      required: [runId, status, documentCount]
      properties:
        runId: { type: string, format: uuid }
        status: { type: string, enum: [queued, running, succeeded, failed, cancelled] }
        documentCount: { type: integer }
        sourceRef: { type: string }
        startedAt: { type: [string, 'null'], format: date-time }
        completedAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }
        mode:
          type: string
          enum: [data, simulation]
          description: En el caso, si el último run fue de pruebas de datos o de simulación.
        restartedAt:
          type: [string, 'null']
          format: date-time
          description: >-
            En el caso, cuándo se reinició la parte de este run después de crearlo: sus
            comprobantes quedaron reemplazados, el run ya no cuenta como aceptado y no
            ofrece descargas. Una simulación se vuelve a enviar con e-NCF nuevos.
        dgiiPhaseClosed:
          type: boolean
          description: >-
            En el caso, true si este run es un reenvío de la simulación que la DGII
            rechazó con «No se encuentra en una fase válida dentro del proceso de
            certificación»: ya había aceptado la simulación anterior y cerrado el paso.
            La simulación aceptada sigue valiendo (checklist.simulationPassed y downloads
            son de ella). Reiniciar la simulación después lo deja en false.
    PartnerRunList:
      type: object
      required: [caseId, runs]
      properties:
        caseId: { type: string, format: uuid }
        runs:
          type: array
          items:
            $ref: '#/components/schemas/PartnerRunSummary'
        correlationId: { type: string }
    PartnerCertificationRunStatus:
      type: object
      required:
        - runId
        - jobId
        - jobStatus
        - runStatus
        - batchIndex
        - batches
        - documentIds
        - currentBatchSummary
        - overallSummary
        - errors
        - evidenceArtifactId
        - b2bSimulationEnabled
      properties:
        runId: { type: string, format: uuid }
        jobId: { type: string, format: uuid }
        jobStatus: { type: string }
        runStatus: { type: string }
        batchIndex: { type: integer, minimum: 0 }
        batches: { type: array, items: { type: object, additionalProperties: true } }
        documentIds: { type: array, items: { type: string, format: uuid } }
        currentBatch:
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: true
        currentBatchSummary: { type: object, additionalProperties: true }
        overallSummary: { type: object, additionalProperties: true }
        startedAt: { type: string, format: date-time }
        completedAt: { type: string, format: date-time }
        errors: { type: array, items: {} }
        summary: { type: object, additionalProperties: true }
        evidenceArtifactId:
          oneOf:
            - type: 'null'
            - type: string
        b2bSimulationEnabled: { type: boolean }
        b2bSimulation:
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: true
        cases:
          type: array
          description: Un elemento por comprobante del set, en el orden en que se envían a la DGII.
          items:
            $ref: '#/components/schemas/PartnerCertificationRunCase'
        correlationId: { type: string }
    PartnerCertificationRunCase:
      type: object
      required: [documentId, type, encf, status, dgiiMessages]
      properties:
        documentId: { type: string, format: uuid }
        caseId:
          description: Columna CasoPrueba del Excel de la DGII (RNC emisor seguido del e-NCF). Null en sets JSON.
          oneOf:
            - type: 'null'
            - type: string
        type: { type: string, example: E31 }
        encf: { type: string, example: E310000000001 }
        batchId:
          oneOf:
            - type: 'null'
            - type: string
        status: { type: string, example: accepted }
        dgiiStatus:
          oneOf:
            - type: 'null'
            - type: string
        trackId:
          oneOf:
            - type: 'null'
            - type: string
        dgiiMessages:
          type: array
          description: Mensajes de la DGII, por ejemplo el motivo de un rechazo.
          items: { type: string }
        superseded:
          type: boolean
          description: true si el comprobante se reemplazó al reiniciar esa parte de las pruebas.
        resendable:
          type: boolean
          description: >-
            true si el comprobante se trabó por un problema de envío y se puede reenviar con
            `POST .../documents/{documentId}/resend`.
    PartnerProductionState:
      type: object
      required: [fiscalAccountId, state, stateVersion]
      properties:
        requestId:
          type: string
          format: uuid
          description: Solo en `POST .../production-activation-requests`.
        fiscalAccountId: { type: string, format: uuid }
        state: { type: string, enum: [inactive, activation_requested, under_review, active, suspended, disabled] }
        stateVersion: { type: integer, minimum: 0 }
        requestedAt:
          type: string
          format: date-time
          description: Solo en `POST .../production-activation-requests`.
        latestRequest:
          description: Solo en `GET .../production`; última solicitud o null.
          oneOf:
            - type: 'null'
            - type: object
              additionalProperties: true
              properties:
                requestId: { type: string, format: uuid }
                status: { type: string, enum: [pending, approved, rejected, cancelled] }
                requestedAt: { type: string, format: date-time }
                decidedAt: { type: [string, 'null'], format: date-time }
        correlationId: { type: string }
    PartnerWebhookDeliveryResponse:
      type: object
      required: [id, endpointId, fiscalAccountId, externalTenantId, eventId, eventType, stateVersion, status, attempts, availableAt, createdAt, updatedAt]
      properties:
        id: { type: string, format: uuid }
        endpointId: { type: string, format: uuid }
        fiscalAccountId: { type: string, format: uuid }
        externalTenantId: { type: string }
        eventId: { type: string, format: uuid }
        eventType: { type: string }
        stateVersion: { type: integer }
        status: { type: string, enum: [queued, running, succeeded, failed] }
        attempts: { type: integer, minimum: 0 }
        availableAt: { type: string, format: date-time }
        responseStatus: { type: [integer, 'null'] }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        correlationId: { type: string }
    PartnerWebhookEndpointRequest:
      type: object
      required: [url]
      additionalProperties: false
      properties:
        name: { type: string, maxLength: 200 }
        url: { type: string, format: uri, maxLength: 2048 }
        eventTypes: { type: array, minItems: 1, items: { type: string, minLength: 1 } }
    PartnerWebhookEndpointResponse:
      type: object
      required: [id, url]
      properties:
        id: { type: string, format: uuid }
        partnerId: { type: string, format: uuid }
        status: { type: string, enum: [active, paused, disabled] }
        replayed: { type: boolean }
        name: { type: [string, 'null'] }
        url: { type: string, format: uri }
        eventTypes: { type: array, items: { type: string } }
        previousSecretExpiresAt:
          type: [string, 'null']
          format: date-time
          description: Fin de la ventana en la que las entregas llevan también la firma del secreto anterior.
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        signingSecret:
          type: string
          description: Solo se devuelve al crear o rotar el endpoint.
        correlationId: { type: string }
    PartnerPlanUsage:
      type: object
      additionalProperties: false
      description: >-
        Plan pagado del Partner en el periodo vigente: límite, margen de tolerancia
        sin costo y consumo (aceptados + en camino) que decide la emisión. `state`:
        within, over_plan (se pasó del plan, dentro del margen), margin_low (le
        queda poco margen; sin margen, ya pasó el 90 % del plan), margin_exhausted
        (llegó al tope: la emisión responde 429), unpaid o unlimited.
      required: [id, name, paid, limit, accepted, reserved, used, remaining, hardLimit, tolerancePct, toleranceStep, nextTolerancePct, marginRemaining, state]
      properties:
        id: { type: [string, 'null'] }
        name: { type: [string, 'null'] }
        paid: { type: boolean }
        limit: { type: [integer, 'null'], description: 'e-CF al mes del plan; null sin límite (A medida).' }
        accepted: { type: integer, minimum: 0 }
        reserved: { type: integer, minimum: 0 }
        used: { type: integer, minimum: 0 }
        remaining: { type: [integer, 'null'], minimum: 0, description: 'Lo que queda dentro del plan (sin el margen).' }
        hardLimit: { type: [integer, 'null'], description: 'Tope de este periodo: plan + margen.' }
        tolerancePct: { type: integer, enum: [0, 10, 20, 30] }
        toleranceStep: { type: [integer, 'null'], minimum: 0, maximum: 3 }
        nextTolerancePct: { type: [integer, 'null'], description: 'Margen del próximo periodo si este cerrara con el consumo actual.' }
        marginRemaining: { type: [integer, 'null'], minimum: 0 }
        state: { type: string, enum: [within, over_plan, margin_low, margin_exhausted, unpaid, unlimited] }
    PartnerWebhookTestRequest:
      type: object
      required: [fiscalAccountId]
      additionalProperties: false
      properties:
        fiscalAccountId: { type: string, format: uuid }
        environment:
          type: string
          enum: [testecf, certecf, ecf]
          default: certecf
          description: Ambiente que aparecerá en el payload de prueba; no emite documentos.
    PartnerWebhookTestResponse:
      type: object
      required: [deliveryId, eventId, eventType, fiscalAccountId, environment, status]
      properties:
        deliveryId: { type: string, format: uuid }
        eventId: { type: string, format: uuid }
        eventType: { type: string, const: webhook.test }
        fiscalAccountId: { type: string, format: uuid }
        environment: { type: string, enum: [certecf, ecf] }
        status: { type: string, const: queued }
        correlationId: { type: string }
    PartnerWebhookEndpointsResponse:
      type: object
      required: [endpoints]
      properties:
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/PartnerWebhookEndpointResponse'
        correlationId: { type: string }
    GenericOkResponse:
      type: object
      required: [ok]
      properties:
        ok:
          type: boolean
      additionalProperties: true
    SandboxReason:
      type: object
      description: >-
        Una razón del veredicto simulado. `effect` `rejects` rechaza el e-CF; `conditional`
        lo deja Aceptado Condicional; `info` solo informa.
      required: [code, dgiiCode, field, message, severity, effect]
      properties:
        code:
          type: [string, 'null']
          description: >-
            Código de ZarelaFact del aviso o error (`details.code`), o null. Un error de estructura
            (XSD) llega como XSD_INVALID, un motivo por campo, con el valor enviado en el mensaje.
        dgiiCode:
          type: [string, 'null']
          description: Código que devuelve la DGII (por ejemplo 1209, 614 o 11105), o null.
        field:
          type: [string, 'null']
          description: Campo del JSON al que se refiere la razón.
        message:
          type: string
        severity:
          type: string
          enum: [error, warning]
        effect:
          type: string
          enum: [rejects, conditional, info]
    SandboxVerdict:
      type: object
      description: >-
        Veredicto simulado. `rejected` si alguna razón rechaza el e-CF;
        `accepted_conditional` si la DGII lo aceptaría con avisos; `accepted` si no hay avisos
        que cambien el resultado. Es una simulación de ZarelaFact, no una respuesta de la DGII.
      required: [status, reasons, disclaimer]
      properties:
        status:
          type: string
          enum: [accepted, accepted_conditional, rejected]
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/SandboxReason'
        disclaimer:
          type: string
    SandboxDocumentView:
      type: object
      description: >-
        Documento del Sandbox. Es un veredicto simulado, nunca un e-CF: sin certificado, sin
        validez fiscal, no enviado a la DGII, sin cargo, sin contar para el plan y conservado 30
        días. Los enlaces llevan al XML y al PDF simulados.
      required: [id, sandbox, encf, documentType, buyer, totals, status, verdict, trackId, createdAt, links]
      properties:
        id:
          type: string
          format: uuid
        sandbox:
          type: boolean
          const: true
        encf:
          type: [string, 'null']
        documentType:
          type: [string, 'null']
          enum: [E31, E32, E33, E34, E41, E43, E44, E45, E46, E47, null]
        buyer:
          type: object
          required: [rnc, name]
          properties:
            rnc:
              type: [string, 'null']
            name:
              type: [string, 'null']
        totals:
          type: object
          description: Montos como texto con 2 decimales, o null si el JSON no traía el monto.
          required: [total, itbis]
          properties:
            total:
              type: [string, 'null']
            itbis:
              type: [string, 'null']
        status:
          type: string
          description: Igual que `verdict.status`.
          enum: [accepted, accepted_conditional, rejected]
        verdict:
          $ref: '#/components/schemas/SandboxVerdict'
        trackId:
          type: string
          description: Identificador del Sandbox (`sandbox-` y el id del documento). No es un TrackID de la DGII.
        createdAt:
          type: string
          format: date-time
        links:
          type: object
          required: [xml, pdf]
          properties:
            xml:
              type: string
            pdf:
              type: string
    SandboxDocumentResponse:
      description: Documento del Sandbox con `correlationId` de la respuesta.
      allOf:
        - $ref: '#/components/schemas/SandboxDocumentView'
      properties:
        correlationId:
          type: string
    SandboxSubmitResponse:
      type: object
      description: Documento guardado con su veredicto simulado. Un rechazo también responde 201.
      required: [ok, environment, document, correlationId]
      properties:
        ok:
          type: boolean
          const: true
        environment:
          type: string
          const: Sandbox
        document:
          $ref: '#/components/schemas/SandboxDocumentView'
        correlationId:
          type: string
    SandboxDocumentsResponse:
      type: object
      required: [items, total, limit, offset, correlationId]
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/SandboxDocumentView'
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
          maximum: 100
        offset:
          type: integer
          minimum: 0
        correlationId:
          type: string
    ErrorResponse:
      type: object
      required: [ok, error]
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        correlationId:
          type: string
