Receptores

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. 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.

curl "https://api.emiti.fravelabs.com/v1/receptores?q=empresa+cliente&limit=10" \
  -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta 200:

{
  "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.
`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.

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/

Devuelve un receptor por id. 404 si no existe o pertenece a otro tenant.

PATCH /v1/receptores/

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").

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/

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:

{ "id": "01948b3c-1234-7890-abcd-ef0123456789", "activo": false }

404 si el receptor no existe.

GET /v1/receptores/padron/

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.

curl "https://api.emiti.fravelabs.com/v1/receptores/padron/80012345-6" \
  -H "Authorization: ApiKey emiti_k_xxxxxxxxxxxxxxxxxxxxxxxx"

Respuesta 200:

{
  "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.

Introducción

Emisión y consulta

Eventos sobre DE

Receptores y series

Datos de referencia

Tipo de operación (`tipo_operacion`)

GET /v1/receptores

POST /v1/receptores

GET /v1/receptores/

PATCH /v1/receptores/

DELETE /v1/receptores/

GET /v1/receptores/padron/

Errores frecuentes

​Tipo de operación (tipo_operacion)

​GET /v1/receptores

​POST /v1/receptores

​GET /v1/receptores/

​PATCH /v1/receptores/

​DELETE /v1/receptores/

​GET /v1/receptores/padron/

​Errores frecuentes

Tipo de operación (`tipo_operacion`)

GET /v1/receptores

POST /v1/receptores

GET /v1/receptores/

PATCH /v1/receptores/

DELETE /v1/receptores/

GET /v1/receptores/padron/

Errores frecuentes