Referencia APIModelos de Datos
Receptor
Schema del objeto receptor — datos del destinatario del documento para operaciones B2B, B2C, B2G y B2F.
El objeto receptor identifica al destinatario del documento electrónico. Su estructura cambia según el tipo de operación: B2C (consumidor final), B2B (otro contribuyente con RUC), B2G (organismo público) o B2F (cliente del exterior).
Schema
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
tipoContribuyente | enum | Sí | CONTRIBUYENTE o NO_CONTRIBUYENTE. Únicos dos valores. Siempre obligatorio, en toda operación |
tipoOperacion | enum | Sí | B2B, B2C, B2G, B2F. Un receptor NO_CONTRIBUYENTE sólo admite B2C o B2F |
tipoContribuyenteReceptor | enum | Condicional | PERSONA_FISICA o PERSONA_JURIDICA — obligatorio cuando tipoContribuyente = CONTRIBUYENTE; no se envía cuando es NO_CONTRIBUYENTE (SIFEN lo rechaza con el código 1303) |
tipoDocumento | enum | Condicional | CEDULA_PARAGUAYA, PASAPORTE, CEDULA_EXTRANJERA, CARNET_DE_RESIDENCIA, INNOMINADO, TARJETA_DIPLOMATICA, OTRO — requerido cuando tipoContribuyente = NO_CONTRIBUYENTE; no se envía cuando es CONTRIBUYENTE |
numeroDocumento | string | Sí, salvo en B2F | RUC base (sin DV), número de CI, pasaporte, etc. El RUC lleva de 3 a 8 caracteres, sin guion ni cero inicial (por ejemplo 80012345). Para el caso innominado se envía el literal "0". En B2F es opcional; si se envía, no puede estar vacío |
nombreRazonSocial | string | Sí | Nombre completo o razón social, de 4 a 255 caracteres. Para el caso innominado se envía el literal "Sin Nombre" |
digitoVerificador | string | Condicional | DV del RUC, un solo dígito — obligatorio cuando tipoContribuyente = CONTRIBUYENTE. Debe corresponder al RUC informado (módulo 11) |
descripcionTipoDocumento | string | Con OTRO | De 9 a 41 caracteres; obligatoria y exclusiva de tipoDocumento = OTRO |
nombreFantasia | string | No | Nombre de fantasía, de 4 a 255 caracteres; se informa además de nombreRazonSocial |
direccion | string | Condicional | Hasta 255 caracteres. Opcional para B2B / B2C / B2G. Obligatoria solo para Nota de Remisión Electrónica (NRE) y operaciones B2F (cliente del exterior con tipoOperacion = B2F). |
numeroCasa | integer | Condicional | Número de casa, 0 si no tiene; obligatorio para B2F y en una FE que informa direccion |
departamento | string | No | Departamento del catálogo de geografía; en una FE se informa junto con ciudad |
codigoDistrito | integer | No | Código del distrito (catálogo geográfico SIFEN) |
ciudad | string | No | Ciudad; en una FE se informa junto con departamento, y la combinación debe existir en el catálogo |
telefono | string | No | Teléfono fijo, de 6 a 15 caracteres |
celular | string | No | Teléfono móvil, de 10 a 20 caracteres |
email | string | No | Email, de 3 a 80 caracteres — Sifende lo usa para enviar el KuDE automáticamente si está configurado |
codigoCliente | string | No | Código libre del emisor para identificar al cliente, de 3 a 15 caracteres. SIFEN no aplica validaciones de negocio y no lo muestra en el KuDE |
pais | enum | No | Por defecto PRY. B2B, B2C y B2G exigen PRY; B2F exige el código ISO de un país distinto de PRY |
Las reglas condicionales de esta tabla están expresadas como if/then en el spec OpenAPI, así que se pueden validar localmente antes de mandar la solicitud.
Reglas clave
- B2B: No envíes
tipoDocumento. El receptor se identifica portipoOperacion: "B2B"+tipoContribuyente: "CONTRIBUYENTE"+tipoContribuyenteReceptor+numeroDocumento(RUC) +digitoVerificador. Los tres últimos son obligatorios: sintipoContribuyenteReceptoro sindigitoVerificadorla API responde400 validation-error. Ladirecciones opcional. - B2C:
tipoContribuyente = NO_CONTRIBUYENTEy generalmentetipoDocumento = CEDULA_PARAGUAYA. Para el receptor innominado (sin identificación) se usatipoDocumento = INNOMINADOconnumeroDocumento: "0"ynombreRazonSocial: "Sin Nombre"— ambos siguen siendo obligatorios. Sólo se permite en Factura Electrónica, no en Nota de Crédito ni de Débito. Ladirecciones opcional. - B2G (gobierno):
tipoOperacion = B2G,tipoContribuyente = CONTRIBUYENTEypais = PRY. ExigenumeroDocumentocon el RUC de 3 a 8 caracteres sin cero inicial, con una letra final A-D opcional,digitoVerificadorde un dígito ytipoContribuyenteReceptor. No envíestipoDocumento. Ladirecciones opcional. Ver Compras públicas. - B2F (exterior): Usar
tipoContribuyente = NO_CONTRIBUYENTE,tipoDocumento = PASAPORTE(oCEDULA_EXTRANJERA,CARNET_DE_RESIDENCIA,TARJETA_DIPLOMATICA,OTRO) ypaiscon el código ISO correspondiente. El país debe ser distinto dePRY;direccionynumeroCasason obligatorios.numeroDocumentoes opcional: si el cliente no tiene un número para informar, omití el campo. Omitídepartamento,ciudad,codigoDistrito,digitoVerificadorytipoContribuyenteReceptor. En una FE, B2F sólo admitetipoTransaccion = PRESTACION_SERVICIOS;VENTA_MERCADERIArecibe400 validation-error. - Nota de Remisión Electrónica (NRE): la
direcciondel receptor es obligatoria porque la NRE documenta un traslado físico de mercadería.
Departamento y ciudad
departamento, codigoDistrito y ciudad se resuelven contra el catálogo de geografía:
departamentoacepta elnamede la categoríadepartamentode/public/enums(PTE_HAYES), el nombre del catálogo (PTE. HAYES) o el código como texto ("15").ciudadacepta elnombreo elcodigo(como texto) de una ciudad del catálogo. Si el nombre del catálogo termina en un calificador entre paréntesis, podés omitirlo:"Asunción"resuelveASUNCION (DISTRITO).- En los nombres no importan mayúsculas, tildes, puntos ni guiones bajos.
- Si el nombre coincide con más de una ciudad del departamento, la API responde
400 validation-error. Enerrores["receptor.ciudad"]lista las opciones con sucodigoDistritoy su código. EnviácodigoDistritoo el código de la ciudad. - SIFEN admite hasta 30 caracteres en la descripción de la ciudad. Si el nombre del catálogo es más largo, el documento lo lleva recortado.