Nominar una factura
POST /api/v1/documento-electronico/:cdc/nominar — identificar al receptor de una factura innominada aprobada.
POST /api/v1/documento-electronico/:cdc/nominar
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, 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
| 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 |
cdc (ruta) | Sí | CDC de la FE: 44 dígitos, comenzando con 01 |
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
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 = CONTRIBUYENTEypais = PRY. OmitítipoDocumento,numeroDocumentoydescripcionTipoDocumento. - B2C: exige
naturaleza = NO_CONTRIBUYENTEypais = PRY. - B2F: exige
naturaleza = NO_CONTRIBUYENTE, país distinto dePRY, dirección y número de casa. Omití las divisiones territoriales paraguayas. - B2C/B2F: omití
tipoContribuyente,rucydigitoVerificador.
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 y geografía.
Ejemplo B2C
{
"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
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
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
| 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 cuando enviás la clave y los errores generales de la API. Consultá la guía de nominación para implementar el flujo.