KilaSifen Docs

Emisores

Representá cada contribuyente y aislá su configuración fiscal.

Un emisor es un RUC habilitado como facturador electrónico. Pertenece a un único consumidor (tu ERP) y sus certificados, timbrados, documentos, eventos y webhooks heredan ese límite: un emisor de otro consumidor responde 404.

Para emitir, el emisor necesita cuatro cosas:

  • perfil fiscal completo (fiscal_profile_complete: true);
  • CSC con su csc_id;
  • un certificado activo y vigente;
  • un timbrado activo que cubra la fecha de emisión.

Las dos primeras se cargan en esta página. Certificado y timbrado se cargan en Certificados y timbrado.

Crear

Hay dos formas de dar de alta un emisor:

  • Desde tu ERP. Una clave de consumidor con el scope emitters:create crea emisores, y cada uno queda a nombre del consumidor de esa clave. Así tu ERP da de alta a cada cliente nuevo sin pasos manuales.
  • Por un administrador. Una clave platform:admin crea emisores para cualquier consumidor, indicado en owner_consumer_id.

Sin emitters:create ni platform:admin, la respuesta es 403 auth.insufficient_scope.

curl -X POST https://TU_API/v1/emitters \
  -H "X-API-Key: $KILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "mi-erp:empresa_42",
    "ruc": "44444401",
    "dv": "7",
    "legal_name": "Empresa Ejemplo S.A.",
    "tax_environment": "test"
  }'
Respuesta 201
{
  "data": {
    "emitter": {
      "id": "3bddb53e-504f-4027-a59b-403968d425ab",
      "external_id": "mi-erp:empresa_42",
      "ruc": "44444401",
      "dv": "7",
      "legal_name": "Empresa Ejemplo S.A.",
      "tax_environment": "test",
      "status": "active",
      "csc_configured": false,
      "csc_id": null,
      "fiscal_profile": null,
      "fiscal_profile_complete": false,
      "created_at": "2026-10-05T16:11:46.289890Z",
      "updated_at": "2026-10-05T16:11:46.289890Z"
    }
  },
  "correlation_id": "0ddcf00f-f531-4158-9634-4374a2a72aae"
}
  • owner_consumer_id es el consumidor dueño del emisor.
    • Con una clave de ERP, omitilo: el emisor queda a nombre de tu consumidor. Si mandás el id de otro consumidor, la respuesta es 403 emitters.owner_not_allowed y no se crea nada.
    • Un administrador lo manda siempre. Si falta, el emisor queda asignado al consumidor de la clave administradora, y no hay endpoint para reasignarlo. Con un id inexistente, la respuesta es 404 consumers.not_found.
  • external_id es opcional y es tu referencia del cliente. Mandalo siempre: con él recuperás el emisor si se pierde la respuesta del alta (ver Listar y recuperar). Es único en toda la plataforma, no por consumidor: si ya existe, la respuesta es 409 emitters.external_id_conflict. Usá un valor que no choque con el de otro integrador, por ejemplo un prefijo de tu ERP y el id interno del cliente.
  • Guardá el id de la respuesta y usalo en todas las rutas.
  • tax_environment tiene que ser el ambiente SIFEN de la instalación (KILA_SIFEN_SIFEN_ENVIRONMENT). Si no lo es, la respuesta es 422 emitters.tax_environment_mismatch, con el valor permitido en details.allowed. Un PATCH tampoco puede pasarlo a otro ambiente: un emisor de producción se da de alta en la instalación de producción.
  • En el alta también se pueden enviar csc, csc_id y fiscal_profile (ver abajo).

A quién darle emitters:create

RUC + DV y external_id son únicos en toda la plataforma. Por eso una clave con emitters:create puede averiguar si un RUC ya está dado de alta (la respuesta es 409 aunque sea de otro consumidor) y puede ocupar un RUC antes que el ERP que de verdad lo atiende. No le alcanza para emitir por ese RUC, porque activar un certificado exige que sea del mismo RUC, pero sí para bloquear su alta hasta que intervenga un administrador. Otorgalo sólo a integradores de confianza.

Listar y recuperar

GET /v1/emitters?external_id=mi-erp:empresa_42

Requiere tenant:read. Devuelve los emisores de tu consumidor, del más nuevo al más viejo; con platform:admin, los de todos los consumidores. Los filtros son opcionales:

ParámetroUso
external_idEl valor exacto que mandaste en el alta.
rucCon o sin DV: 44444401 o 44444401-7.
limitDe 1 a 200 resultados; por defecto, 50.
Respuesta 200
{
  "data": {
    "emitters": [
      {
        "id": "3bddb53e-504f-4027-a59b-403968d425ab",
        "external_id": "mi-erp:empresa_42",
        "ruc": "44444401",
        "dv": "7",
        "legal_name": "Empresa Ejemplo S.A.",
        "tax_environment": "test",
        "status": "active",
        "csc_configured": false,
        "csc_id": null,
        "fiscal_profile": null,
        "fiscal_profile_complete": false,
        "created_at": "2026-10-05T16:11:46.289890Z",
        "updated_at": "2026-10-05T16:11:46.289890Z"
      }
    ]
  },
  "correlation_id": "5a1c4e1e-3f0b-4f3e-9d55-2f6a8f0b7c11"
}

Si el alta se cortó antes de que llegara la respuesta (un timeout o una caída de red), no sabés si el emisor se creó. No repitas el alta a ciegas:

  1. Buscalo con GET /v1/emitters?external_id=....
  2. Si aparece, guardá su id y seguí con el certificado y el timbrado.
  3. Si no aparece, repetí el alta. Si esa respuesta es 409 emitters.external_id_conflict, el primer intento sí se hizo: volvé al paso 1.

Si el alta responde 409 emitters.tax_id_conflict, buscá con ?ruc=. Si el emisor aparece, ya es tuyo. Si no aparece, ese RUC está dado de alta a nombre de otro consumidor: hablá con el administrador de la plataforma.

Identidad fiscal

RUC, DV y razón social viajan en cada documento (dRucEm, dDVEmi, dNomEmi), y RUC y DV además forman el CDC. Por eso KilaSifen los valida en el alta (y legal_name también al editarlo):

  • ruc: de 3 a 8 caracteres, sin DV, con el patrón oficial [1-9][0-9]*[0-9A-D]? (no empieza con 0).
  • dv: un dígito, que tiene que ser el módulo 11 del RUC. Si no lo es, la respuesta es 422 emitters.dv_mismatch (el SIFEN lo rechazaría con 1253).
  • legal_name: la razón social del RUC, de 4 a 255 caracteres sin contar los espacios de los extremos (422 emitters.legal_name_invalid).

Un campo con formato inválido responde 422 request.validation_failed, con el campo en details.errors. El par RUC + DV es único en la plataforma: si se repite, la respuesta es 409 emitters.tax_id_conflict. RUC y DV no se pueden cambiar después: un PATCH no los modifica. legal_name sí se puede cambiar con PATCH y tenant:write.

Razón social en el ambiente de pruebas

El MT v150 (D105, validación 1263) pide en pruebas un texto fijo en dNomEmi, y la Guía de Pruebas de la DNIT de febrero de 2026 pide otro. Cuál acepta el SIFEN de pruebas está NO DETERMINADO. KilaSifen usa legal_name, salvo que el operador configure KILA_SIFEN_TEST_EMITTER_NAME_LITERAL, que reemplaza dNomEmi sólo en los emisores test. En legal_name cargá siempre la razón social real. En producción, un emisor cuyo legal_name sea el texto de pruebas del MT no puede emitir: sus documentos quedan failed con documents.emisor.test_name_in_production.

Perfil fiscal

El grupo gEmis de cada documento se arma con el RUC, el DV y la razón social del emisor más su perfil fiscal. El bloque emisor de un documento puede repetir esos datos, pero no cambiarlos (ver Facturas).

Sin perfil no se pueden crear documentos: la API responde 422 emitters.fiscal_profile_required. Para cargarlo, usá PATCH con tenant:write, o mandalo en el alta.

curl -X PATCH https://TU_API/v1/emitters/EMITTER_ID \
  -H "X-API-Key: $KILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fiscal_profile": {
      "tipo_contribuyente": 2,
      "actividades_economicas": [
        {"codigo": "62010", "descripcion": "ACTIVIDADES DE PROGRAMACION INFORMATICA"}
      ],
      "domicilio": {
        "direccion": "CALLE EJEMPLO",
        "numero_casa": "123",
        "departamento": 1,
        "ciudad": 1,
        "descripcion_ciudad": "ASUNCION (DISTRITO)",
        "telefono": "021123456",
        "email": "facturacion@example.com"
      },
      "establecimientos": []
    }
  }'
CampoUso
tipo_contribuyenteObligatorio: 1 persona física, 2 persona jurídica (iTipCont, entra en el CDC).
tipo_regimenOpcional: código de 1 a 8 (cTipReg).
nombre_fantasiaOpcional: de 4 a 255 caracteres.
actividades_economicasObligatorio: de 1 a 9, cada una con codigo y descripcion.
domicilioObligatorio: dirección del local que emite.
establecimientosOpcional: dirección propia de un establecimiento, con su código de 3 dígitos en establecimiento y los mismos campos que domicilio.

Los campos de domicilio son estos:

  • direccion, obligatoria.
  • numero_casa, de 1 a 6 dígitos (0 si la dirección no tiene numeración).
  • complemento_1 y complemento_2, opcionales.
  • departamento, obligatorio: se valida contra el catálogo oficial y KilaSifen guarda su descripción oficial. descripcion_departamento es opcional, pero si la mandás tiene que coincidir con el código.
  • distrito y descripcion_distrito, opcionales; van juntos.
  • ciudad y descripcion_ciudad, obligatorios.
  • telefono (de 6 a 15 caracteres, con prefijo) y email, obligatorios.
  • denominacion_sucursal, opcional (hasta 30 caracteres).

Dentro de fiscal_profile, un campo con formato inválido o desconocido responde 422 request.validation_failed. Un departamento inexistente, una descripción de departamento que no coincide o un distrito sin descripción responden 422 emitters.fiscal_profile_invalid, con details.field y details.reason.

Todo el perfil tiene que coincidir con lo declarado en el RUC, pero KilaSifen sólo valida el departamento:

  • Distrito y ciudad no se validan localmente. Copiá código y descripción tal como figuran en tu RUC: si no coinciden, el SIFEN rechaza con 1255 a 1260.
  • Una actividad económica que no es del RUC se rechaza con 1261 o 1262.
  • Que el SIFEN rechace una dirección, un teléfono, un email o un nombre de fantasía distintos del padrón es NO DETERMINADO.

Un PATCH que incluye fiscal_profile reemplaza el perfil completo. Uno que no lo incluye lo deja como está. La respuesta del emisor trae fiscal_profile y fiscal_profile_complete.

Emisores anteriores al perfil fiscal

Un emisor creado antes de que KilaSifen exigiera el perfil quedó con el perfil vacío (fiscal_profile_complete: false), y no puede crear documentos tipados hasta que se lo cargues con PATCH.

CSC

El CSC (código de seguridad del contribuyente) lo entrega la SET junto con su identificador (IdCSC). Es de 32 caracteres alfanuméricos y KilaSifen sólo lo usa para calcular el hash del QR. La API nunca lo devuelve: la respuesta trae csc_configured y csc_id.

Para cargarlo, mandalo en el alta (alcanza con el scope del alta, emitters:create) o usá un PATCH con una clave que tenga tenant:write y secrets:write. En el PATCH, si falta cualquiera de los dos scopes, la respuesta es 403 auth.insufficient_scope.

curl -X PATCH https://TU_API/v1/emitters/EMITTER_ID \
  -H "X-API-Key: $KILA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"csc\": \"$KILA_CSC\", \"csc_id\": \"1\"}"
  • csc_id admite de 1 a 4 dígitos, entre 1 y 9999, y se guarda con cuatro (1 → 0001). Un 0 responde 422 emitters.csc_id_invalid.
  • Hacen falta los dos. Sin CSC o sin csc_id no se puede armar el QR: el documento queda failed con emitters.csc_required y el KuDE responde 409 emitters.csc_required.
  • Con el emisor desactivado, cambiar el CSC responde 409 emitters.inactive.
  • KilaSifen guarda un solo CSC por emisor, aunque la SET permite hasta dos activos (MT v150 §13.8.1).
  • El QR se calcula al firmar. Si cambiás el CSC, los documentos ya firmados conservan el QR que se calculó con el anterior. Mantené el CSC al día: el SIFEN responde 2501 si el CSC no está vigente en la fecha de emisión (NT 10).

Comprobar preparación

GET /v1/emitters/{emitter_id}/health

Requiere tenant:read.

Respuesta 200
{
  "data": {
    "health": {
      "emitter_id": "3bddb53e-504f-4027-a59b-403968d425ab",
      "emitter_status": "active",
      "has_active_certificate": true,
      "certificate_valid_until": "2027-10-05T16:11:50Z",
      "has_active_stamping": true,
      "stamping_number": "12345678",
      "stamping_valid_on": "2026-10-05",
      "queue_queued_count": 0,
      "queue_retry_count": 0,
      "queue_failed_count": 0,
      "last_document_id": null,
      "last_document_status": null,
      "checked_at": "2026-10-05T16:11:53.059023Z"
    }
  },
  "correlation_id": "9f6d0c14-daaa-40f0-ae67-e5adf44b03e1"
}
  • has_active_certificate dice si hay un certificado activo, aunque esté vencido. Para saber si vale, mirá certificate_valid_until.
  • has_active_stamping y stamping_number se evalúan para stamping_valid_on, la fecha del servidor. El documento usa el timbrado vigente en su propia fecha de emisión (hora de Paraguay), así que con fechas de emisión pasadas o futuras el resultado puede diferir.
  • Los contadores queue_* cuentan sólo los últimos 200 jobs del emisor.
  • health no informa el CSC ni el perfil fiscal. Para eso, mirá csc_configured y fiscal_profile_complete en GET /v1/emitters/{emitter_id}.

Desactivar

POST /v1/emitters/{emitter_id}/deactivate

Alcanza con tenant:write del consumidor dueño, así que restringí ese scope.

La desactivación es definitiva: la API no permite reactivar un emisor, y llamarla otra vez devuelve 200 sin cambios.

Desde ese momento, cualquier operación nueva responde 409 emitters.inactive. Eso incluye emisiones, eventos, consultas al SIFEN, cambios de certificados, timbrados y CSC, y entregas de webhooks.

Lo que sigue disponible:

  • las lecturas;
  • un PATCH de legal_name o de fiscal_profile.

Los jobs que ya estaban en cola se frenan antes de descifrar secretos o de contactar servicios externos. Esos documentos quedan en queued: nunca llegan a un estado final ni disparan un webhook (ver Estados y reintentos).

En esta página