> ## Documentation Index > Fetch the complete documentation index at: https://docs.emiti.fravelabs.com/llms.txt > Use this file to discover all available pages before exploring further. # Receptores > Catálogo de clientes del tenant: alta, edición, baja y consulta del padrón DNIT. El catálogo de receptores guarda los clientes de tu tenant para que no tengas que reenviar sus datos completos en cada emisión — buscalos por `GET /v1/receptores` y usá el resultado para armar el objeto `receptor` de [`POST /v1/de/emitir`](/api-reference/emitir). Todas las operaciones (salvo la consulta al padrón) están **filtradas por tenant**: un receptor pertenece siempre al tenant que lo creó, y un `GET`/`PATCH`/`DELETE` sobre un id de otro tenant devuelve `404` (no existe, no que no tenés permiso). ## Tipo de operación (`tipo_operacion`) Cada receptor tiene un `tipo_operacion` que determina qué campos son obligatorios: | Valor | Tipo | Campos obligatorios | Notas | | ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | | `1` | Contribuyente (B2B) | `ruc`, `tipo_contribuyente` (`1` física o `2` jurídica) | `codigo_pais` debe ser `"PRY"` si se envía. | | `3` | Organismo del Estado (B2G) | `ruc`, `tipo_contribuyente: 2` | Un organismo del Estado siempre es persona jurídica. | | `4` | No domiciliado (B2F) | `documento_tipo` (`2` pasaporte, `3` cédula extranjera o `9` otro), `documento_numero`, `codigo_pais` (≠ `"PRY"`), `direccion` | No lleva `ruc`. | ## GET /v1/receptores Listado paginado con búsqueda fuzzy en nombre, nombre de fantasía y RUC. | Param | Tipo | Requerido | Descripción | | ------------------- | ------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `q` | `string` (máx 120) | no | Término de búsqueda (mínimo 2 chars para activar el filtro fuzzy). | | `limit` | `integer` (1–100) | no (default `50`) | Cantidad de resultados. | | `offset` | `integer` (≥ 0) | no (default `0`) | Offset para paginación. | | `incluir_inactivos` | `boolean` | no (default `false`) | Incluir receptores marcados como inactivos (soft-deleted). | | `tipo_operacion` | `integer` (`1`, `3` ó `4`), repetible | no | Filtra por tipo de cliente. Repetí el parámetro para varios valores (`?tipo_operacion=1&tipo_operacion=4`). Sin filtro, devuelve todos los tipos. | ```bash theme={null} curl "https://api.emiti.fravelabs.com/v1/receptores?q=empresa+cliente&limit=10" \ -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx" ``` **Respuesta `200`:** ```json theme={null} { "receptores": [ { "id": "01948b3c-1234-7890-abcd-ef0123456789", "ruc": "80012345-6", "documento_tipo": 1, "documento_numero": "12345678", "nombre": "Empresa Cliente SA", "nombre_fantasia": null, "direccion": "Av. Mariscal López 1234", "telefono": null, "email": "facturacion@cliente.com", "tipo_operacion": 1, "tipo_contribuyente": 2, "codigo_pais": "PRY", "activo": true, "created_at": "2026-06-01T10:00:00", "updated_at": "2026-06-01T10:00:00" } ], "total": 1, "limit": 10, "offset": 0, "page": 1, "total_pages": 1 } ``` ## POST /v1/receptores Crea un receptor en el catálogo del tenant. | Campo | Tipo | Default | Requerido | Descripción | | -------------------- | ------------------------------- | ------- | ----------- | ----------------------------------------------------------- | | `nombre` | `string` (1–255) | — | sí | Nombre o razón social. | | `nombre_fantasia` | `string` (máx 255) | `null` | no | | | `ruc` | `string` (formato `XXXXXXXX-D`) | `null` | condicional | Ver [tipo de operación](#tipo-de-operación-tipo_operacion). | | `documento_tipo` | `integer` (1–99) | `5` | condicional | Tipo de documento (no domiciliado). | | `documento_numero` | `string` (máx 20) | `null` | condicional | | | `direccion` | `string` (máx 255) | `null` | condicional | Obligatoria para no domiciliado. | | `telefono` | `string` (máx 20) | `null` | no | | | `email` | `string` (máx 255) | `null` | no | Validación blanda (presencia de `@` y dominio). | | `tipo_operacion` | `integer` (`1`, `3` ó `4`) | — | sí | Ver tabla arriba. | | `tipo_contribuyente` | `integer` (1–2) | `null` | condicional | `1` física, `2` jurídica. | | `codigo_pais` | `string` (3 chars) | `"PRY"` | no | Código ISO 3166-1 alfa-3. | ```bash theme={null} curl -s "https://api.emiti.fravelabs.com/v1/receptores" \ -X POST \ -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "nombre": "Empresa Cliente SA", "ruc": "80012345-6", "tipo_operacion": 1, "tipo_contribuyente": 2, "direccion": "Av. Mariscal López 1234", "email": "facturacion@cliente.com" }' ``` La respuesta `200` devuelve el receptor creado con el mismo shape que el listado. Si ya existe un receptor con el mismo `ruc` en tu catálogo (solo aplica a `tipo_operacion: 1` o `3`, que sí guardan RUC), la API devuelve `409` con el `id` del receptor existente en el mensaje — no se crea un duplicado. ## GET /v1/receptores/{receptor_id} Devuelve un receptor por id. `404` si no existe o pertenece a otro tenant. ## PATCH /v1/receptores/{receptor_id} Actualización parcial — solo los campos presentes en el body se modifican. Acepta los mismos campos que `POST`, todos opcionales. Si el PATCH incluye `tipo_operacion` (cambio de tipo de cliente), tenés que enviar en la misma request **todos** los campos obligatorios del tipo nuevo — e-Miti no valida contra el estado ya guardado en BD. Al cambiar de tipo, los campos que no aplican al tipo nuevo se limpian automáticamente (por ejemplo, pasar de no domiciliado a contribuyente borra `documento_tipo`/`documento_numero` y fija `codigo_pais: "PRY"`). ```bash theme={null} curl -s "https://api.emiti.fravelabs.com/v1/receptores/01948b3c-1234-7890-abcd-ef0123456789" \ -X PATCH \ -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"telefono": "0981123456"}' ``` Devuelve el receptor actualizado, `404` si no existe. ## DELETE /v1/receptores/{receptor_id} Soft-delete: marca el receptor como `activo: false` sin borrar la fila (los DE ya emitidos guardan un snapshot del receptor, no una referencia viva). **Respuesta `200`:** ```json theme={null} { "id": "01948b3c-1234-7890-abcd-ef0123456789", "activo": false } ``` `404` si el receptor no existe. ## GET /v1/receptores/padron/{ruc} Proxy del padrón público de contribuyentes (turuc.com.py) para consultar un RUC antes de darlo de alta. Requiere autenticación (como el resto de la API) aunque no consulta datos del tenant. ```bash theme={null} curl "https://api.emiti.fravelabs.com/v1/receptores/padron/80012345-6" \ -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx" ``` **Respuesta `200`:** ```json theme={null} { "razon_social": "Empresa Cliente SA", "ruc": "80012345-6", "dv": 6, "estado": "ACTIVO", "es_persona_juridica": true } ``` | Status | Causa | | ------ | ----------------------------------------------------------- | | `400` | El RUC enviado tiene menos de 3 caracteres. | | `404` | El padrón no encontró el RUC. | | `502` | El padrón no respondió o devolvió una respuesta inesperada. | ## Errores frecuentes | Código | Status | Causa | | ----------------------------- | ------------ | ----------------------------------------------------------------------------------------------- | | `VALIDACION_MULTIPLES_CAMPOS` | 400 | Campos requeridos faltantes o inválidos según `tipo_operacion`. Revisar `extra.errores[]`. | | `NOT_FOUND` | 404 | El `receptor_id` no existe o pertenece a otro tenant. | | `BAD_REQUEST` | 400 | Falta el `tenant_id` en las claims del token (reautenticate). | | `SERVICE` | 409 (POST) | Ya existe un receptor con ese `ruc` en tu catálogo. El mensaje incluye el `id` del existente. | | `SERVICE` | 502 (padrón) | El padrón externo no respondió, devolvió un error de servidor, o la respuesta llegó malformada. |