import { Aside } from "@astrojs/starlight/components";

`POST /api/v1/ecf` responde `201 Created` en una emisión nueva, o `200 OK`
si la `Idempotency-Key` o el `internalNumber` ya se habían usado (ver
[Endpoints y semántica](/emision/endpoints-y-semantica/)). `GET /ecf/{id}`
devuelve exactamente la misma forma.

```json
{
  "id": "0194f2c1-8a3e-7b21-9c44-1f2e3d4a5b6c",
  "status": "accepted",
  "encf": "E310000000042",
  "type": 31,
  "environment": "Test",
  "sequenceExpiresOn": "31-12-2027",
  "issueDate": "21-02-2026",
  "issuedAt": "2026-02-21T10:30:05-04:00",
  "signedAt": "2026-02-21T10:30:05-04:00",
  "securityCode": "aB3xK9",
  "qrUrl": "https://ecf.dgii.gov.do/testecf/consultatimbre?rncemisor=...",
  "submitsRfce": false,
  "internalNumber": "FAC-2026-00042",
  "montoTotal": 2360.0,
  "buyerRnc": "131880681",
  "buyerName": "Mi Cliente SRL",
  "documentHash": "3f8a1c9e2b7d4f60a5c8e1d2b3a4f5061c7e8d9f0a1b2c3d4e5f60718293a4b5",
  "toleranceWarning": null,
  "signedDuringContingency": false,
  "dgii": {
    "trackId": "TRACK-ABC-123",
    "status": "Aceptado",
    "statusCode": 1,
    "sequenceUsed": true,
    "messages": [],
    "submittedAt": "2026-02-21T10:30:06-04:00",
    "receivedAt": "2026-02-21T10:30:06-04:00",
    "processedAt": "2026-02-21T10:30:06-04:00"
  },
  "links": {
    "self": "/api/v1/ecf/0194f2c1-8a3e-7b21-9c44-1f2e3d4a5b6c",
    "xml": "/api/v1/ecf/0194f2c1-8a3e-7b21-9c44-1f2e3d4a5b6c/xml",
    "rfceXml": null,
    "representation": "/api/v1/ecf/0194f2c1-8a3e-7b21-9c44-1f2e3d4a5b6c/representation"
  }
}
```

Es identidad fiscal más resumen comercial más estado: `montoTotal`,
`buyerRnc`, `buyerName` y `documentHash` son el mismo resumen que trae cada
fila del listado (`GET /ecf`). El desglose por línea (retenciones, ITBIS
por línea, descuentos) solo vive en el XML firmado, en `links.xml`.

## `dgii`: el intercambio con la DGII

`null` mientras el comprobante no se haya enviado todavía. Una vez enviado:

| Campo          | Nota                                                                                                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `trackId`      | El identificador que asignó la DGII a este envío.                                                                           |
| `status`       | El estado tal cual lo manda la DGII, como texto ("Aceptado", "Rechazado"...).                                               |
| `statusCode`   | `1` aceptado, `2` rechazado, `3` en proceso, `4` aceptado condicional.                                                      |
| `sequenceUsed` | Si la DGII consumió el e-NCF. `false` indica que no lo consumió: un comprobante rechazado con este valor se puede reenviar. |
| `messages`     | Observaciones de la DGII, `{ code, value }`.                                                                                |
| `submittedAt`  | Cuándo NovaFE confirmó la recepción del envío.                                                                              |
| `receivedAt`   | La fecha de recepción que informó la DGII. Ausente si no la dio (por ejemplo, en un RFCE).                                  |
| `processedAt`  | Cuándo NovaFE registró el resultado definitivo.                                                                             |

## `links`

Rutas relativas a este mismo comprobante: `self` (este mismo recurso),
`xml` (el XML firmado), `rfceXml` (el RFCE, solo si `submitsRfce` es
`true`) y `representation` (la representación impresa en PDF, ver
[Representación impresa](/representacion-impresa/)).

## Estados

```
signed → submitted → accepted / accepted_conditional / rejected
   ↑  │          └──────► review   (la DGII no resolvió tras el ladder de polling)
   │  └───────► failed             (agotó el backoff de transporte, o rechazo del gateway)
   └── falla pasajera de la DGII con el número libre: vuelve a signed y se reenvía
```

| Estado                 | Significa                                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `signed`               | Firmado y encolado. Todavía no se intentó el envío, el envío está en curso, o NovaFE espera para reenviarlo tras una falla pasajera de la DGII. |
| `submitted`            | Enviado a la DGII, con `trackId`, esperando resultado.                                                                                          |
| `accepted`             | La DGII lo aceptó: fiscalmente válido.                                                                                                          |
| `accepted_conditional` | Válido fiscalmente, con una observación de la DGII.                                                                                             |
| `rejected`             | La DGII lo rechazó. Es definitivo, salvo que haya dejado libre el e-NCF (`dgii.sequenceUsed` en `false`), caso en el que se puede reenviar.     |
| `review`               | La DGII no dio un resultado definitivo después de varios intentos de consulta.                                                                  |
| `failed`               | No se pudo transmitir después de agotar los reintentos de transporte.                                                                           |

Si tu cuenta tiene desactivada la espera del resultado (ver
[Ajustes del contribuyente](/cuenta/ajustes/)), `signed` es el estado normal de
la respuesta de `POST /ecf`, con `dgii` en `null`: el resultado llega después
por webhook o consultando el comprobante.

`review` y `failed` se reencolan con `POST /ecf/{id}/retry` (vuelve a
`signed`, responde `202`). Un `rejected` también, pero solo si la DGII dejó libre
el e-NCF; si lo consumió, responde `409`. Los demás estados son terminales. El
detalle, incluido el reintento automático ante fallas pasajeras de la DGII y el
historial de envíos, está en
[Rechazos y reintentos](/emision/rechazos-y-reintentos/).

<Aside type="caution" title="Cuándo un e-NCF queda invalidado">
  Si el pipeline falla antes de llegar a encolar (un error de validación fiscal
  inesperado, del XSD o de la firma), `POST /ecf` devuelve un error y el e-NCF
  que se iba a usar se pierde: no queda un comprobante persistido al que
  reintentar. Si numeras tú, no se pierde nada, porque NovaFE no consumió el
  número. Un `rejected` de la DGII invalida el número de forma permanente cuando
  la DGII lo consumió. Si la DGII informa que no lo consumió, el número sigue
  asociado a ese mismo comprobante y puedes reenviarlo, pero nunca se reasigna a
  un comprobante distinto.
</Aside>

## `signedDuringContingency`

`true` si tu tenant estaba en modo de contingencia (ver
[Representación impresa](/representacion-impresa/) y la documentación de
contingencia) en el momento de firmar. No cambia nada del XML: solo decide
si la representación impresa lleva la leyenda de contingencia. No lo
confundas con `deferredDelivery` del payload (envío diferido), que es una
autorización previa y permanente para operar offline, no algo que dependa
del estado de la plataforma al momento de firmar.