# Nominar una factura (/docs/referencia/documentos-electronicos/nominar)



## POST /api/v1/documento-electronico/:cdc/nominar [#post-apiv1documento-electronicocdcnominar]

Identifica al receptor de una FE originalmente innominada mediante un evento de nominación. Requiere una factura en estado `APROBADO` o `APROBADO_OBSERVACION`, con receptor original no contribuyente, `INNOMINADO` y número de documento `"0"`.

La operación es síncrona y está disponible en DEV y PROD. SANDBOX devuelve [`422 sandbox-operation-not-supported`](/docs/solucion-problemas/sandbox-operation-not-supported), sin registrar ni enviar un evento. La nominación no modifica el CDC, XML firmado ni KuDE originales y no consume numeración ni cupo de emisión.

## Headers y CDC [#headers-y-cdc]

| Dato              | Requerido | Descripción                                                                                                   |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `Authorization`   | Sí        | `Bearer {api-key}` del contribuyente y ambiente de la factura                                                 |
| `Content-Type`    | Sí        | `application/json`                                                                                            |
| `Idempotency-Key` | No        | Clave estable para recuperar la respuesta de la misma intención; ver [idempotencia](/docs/guias/idempotencia) |
| `cdc` (ruta)      | Sí        | CDC de la FE: 44 dígitos, comenzando con `01`                                                                 |

## Cuerpo de la solicitud [#cuerpo-de-la-solicitud]

| Campo      | Tipo     | Requerido | Descripción                                             |
| ---------- | -------- | --------- | ------------------------------------------------------- |
| `motivo`   | `string` | Sí        | De 5 a 500 caracteres, no compuesto sólo por espacios   |
| `receptor` | `object` | Sí        | Identificación del receptor según las reglas siguientes |

### Receptor de la nominación [#receptor-de-la-nominación]

Este objeto tiene nombres distintos al receptor de emisión: usa `naturaleza`, `ruc`, `tipoContribuyente` y `codigoCiudad`.

| Campo                      | Tipo      | Requerido                  | Descripción                                                                                                                          |
| -------------------------- | --------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `naturaleza`               | `enum`    | Sí                         | `CONTRIBUYENTE` o `NO_CONTRIBUYENTE`                                                                                                 |
| `tipoOperacion`            | `enum`    | Sí                         | `B2B`, `B2C` o `B2F`; no admite B2G                                                                                                  |
| `pais`                     | `enum`    | Sí                         | Código del país; no tiene valor por defecto                                                                                          |
| `nombreRazonSocial`        | `string`  | Sí                         | De 4 a 255 caracteres, no vacío                                                                                                      |
| `tipoContribuyente`        | `enum`    | Para B2B                   | `PERSONA_FISICA` o `PERSONA_JURIDICA`                                                                                                |
| `ruc`                      | `string`  | Para B2B                   | De 3 a 8 dígitos, sin DV                                                                                                             |
| `digitoVerificador`        | `string`  | Para B2B                   | Un dígito; debe corresponder al RUC                                                                                                  |
| `tipoDocumento`            | `enum`    | Para B2C/B2F               | `CEDULA_PARAGUAYA`, `PASAPORTE`, `CEDULA_EXTRANJERA`, `CARNET_DE_RESIDENCIA`, `TARJETA_DIPLOMATICA` u `OTRO`; no admite `INNOMINADO` |
| `numeroDocumento`          | `string`  | Para B2C/B2F               | De 1 a 20 caracteres: letras ASCII, dígitos o guion                                                                                  |
| `descripcionTipoDocumento` | `string`  | Sólo para `OTRO`           | Obligatoria con `OTRO`, de 9 a 41 caracteres después de quitar espacios de los extremos; se omite para otros tipos                   |
| `direccion`                | `string`  | Para B2F                   | Hasta 255 caracteres; opcional para B2B/B2C                                                                                          |
| `numeroCasa`               | `integer` | Si hay dirección           | De 0 a 999999; obligatorio para B2F                                                                                                  |
| `departamento`             | `enum`    | Si hay dirección paraguaya | Valor del catálogo `departamento`; no se admite en B2F                                                                               |
| `codigoDistrito`           | `integer` | No                         | Código positivo del distrito, compatible con departamento y ciudad; no se admite en B2F                                              |
| `codigoCiudad`             | `integer` | Si hay dirección paraguaya | Código positivo de ciudad del departamento y, si se informa, del distrito; no se admite en B2F                                       |
| `nombreFantasia`           | `string`  | No                         | De 4 a 255 caracteres                                                                                                                |
| `telefono`                 | `string`  | No                         | De 6 a 15 caracteres                                                                                                                 |
| `celular`                  | `string`  | No                         | De 10 a 20 caracteres                                                                                                                |
| `email`                    | `string`  | No                         | Dirección de correo válida                                                                                                           |
| `codigoCliente`            | `string`  | No                         | De 3 a 15 caracteres                                                                                                                 |

* **B2B:** exige `naturaleza = CONTRIBUYENTE` y `pais = PRY`. Omití `tipoDocumento`, `numeroDocumento` y `descripcionTipoDocumento`.
* **B2C:** exige `naturaleza = NO_CONTRIBUYENTE` y `pais = PRY`.
* **B2F:** exige `naturaleza = NO_CONTRIBUYENTE`, país distinto de `PRY`, dirección y número de casa. Omití las divisiones territoriales paraguayas.
* **B2C/B2F:** omití `tipoContribuyente`, `ruc` y `digitoVerificador`.

Para B2B/B2C, si informás dirección, también son obligatorios número de casa, departamento y ciudad. Sin dirección, omití el número de casa y las divisiones territoriales. Consultá los [catálogos de enumeraciones](/docs/referencia/catalogos/enumeraciones) y [geografía](/docs/referencia/catalogos/geografia).

### Ejemplo B2C [#ejemplo-b2c]

```json
{
  "motivo": "Identificación del cliente a su solicitud",
  "receptor": {
    "naturaleza": "NO_CONTRIBUYENTE",
    "tipoOperacion": "B2C",
    "pais": "PRY",
    "tipoDocumento": "CEDULA_PARAGUAYA",
    "numeroDocumento": "1234567",
    "nombreRazonSocial": "Juan Pérez"
  }
}
```

## Respuesta [#respuesta]

**HTTP `200`** devuelve directamente el objeto del evento, sin envoltorio `data`. Revisá `estadoEvento`: `APROBADO` confirma la nominación; `RECHAZADO` indica que SIFEN rechazó el evento aunque el HTTP sea `200`.

| Campo                                                        | Descripción                                                 |
| ------------------------------------------------------------ | ----------------------------------------------------------- |
| `eventoSifenId`, `documentoElectronicoId`, `contribuyenteId` | Identificadores del evento, documento y contribuyente       |
| `ambiente`                                                   | Ambiente de la operación                                    |
| `tipoEvento`                                                 | `NOMINACION`                                                |
| `estadoEvento`                                               | `APROBADO` o `RECHAZADO` en una respuesta confirmada        |
| `cdc`, `motivo`                                              | Documento y motivo de la nominación                         |
| `protocoloAutorizacion`                                      | Protocolo comunicado por SIFEN                              |
| `codigoRespuesta`                                            | Primer código de respuesta de SIFEN                         |
| `mensajeRespuesta`                                           | Mensajes con formato `[código] mensaje`, separados por `\|` |
| `fechaCreacion`, `fechaProcesamiento`                        | Fechas del evento                                           |

Sólo una nominación `APROBADO` aporta el receptor efectivo para la precarga de NCE/NDE en el panel.

## Resultado incierto y reintentos [#resultado-incierto-y-reintentos]

Si SIFEN no confirma el resultado, la API conserva el evento como `ENVIADO` y responde `503 evento-nominacion-error` con `Retry-After: 2`. No equivale a una aprobación ni a un rechazo. Esperá el intervalo y repetí la misma solicitud, con la misma `Idempotency-Key` si la enviaste.

La confirmación y, si se comprueba que el evento no existe, como máximo un reenvío se realizan dentro de la petición. No hay recuperación automática en segundo plano. No cambies el receptor, motivo o clave mientras el resultado siga incierto. Una nominación aprobada no se reemplaza mediante una nueva solicitud; el replay con la clave original permite recuperar su respuesta.

## Errores [#errores]

| HTTP | Tipo                                                       | Qué revisar                                                                           |
| ---- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| 400  | `validation-error`, `invalid-enum-value`, `invalid-format` | Campos, formatos y valores del receptor o la clave                                    |
| 400  | `evento-nominacion-error`                                  | Elegibilidad de la factura, geografía o datos indicados en `detail`                   |
| 403  | `document-archived`                                        | El período de acceso al documento finalizó. No aplica a una clave ya registrada       |
| 404  | `documento-electronico-not-found`                          | CDC no encontrado para la API key y su ambiente, o documento cuya conservación venció |
| 409  | `evento-nominacion-error`                                  | Conflicto con una nominación activa o aprobada                                        |
| 422  | `sandbox-operation-not-supported`                          | Usá el ambiente DEV o PROD correspondiente a la factura                               |
| 503  | `evento-nominacion-error`                                  | Resultado sin confirmar; respetá `Retry-After`                                        |

También se aplican los [errores de idempotencia](/docs/guias/idempotencia) cuando enviás la clave y los [errores generales de la API](/docs/referencia/errores). Consultá la [guía de nominación](/docs/guias/nominar-factura) para implementar el flujo.
