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:createcrea 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:admincrea emisores para cualquier consumidor, indicado enowner_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"
}'{
"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_ides el consumidor dueño del emisor.- Con una clave de ERP, omitilo: el emisor queda a nombre de tu consumidor.
Si mandás el
idde otro consumidor, la respuesta es403 emitters.owner_not_allowedy 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.
- Con una clave de ERP, omitilo: el emisor queda a nombre de tu consumidor.
Si mandás el
external_ides 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 es409 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
idde la respuesta y usalo en todas las rutas. tax_environmenttiene que ser el ambiente SIFEN de la instalación (KILA_SIFEN_SIFEN_ENVIRONMENT). Si no lo es, la respuesta es422 emitters.tax_environment_mismatch, con el valor permitido endetails.allowed. UnPATCHtampoco 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_idyfiscal_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_42Requiere 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ámetro | Uso |
|---|---|
external_id | El valor exacto que mandaste en el alta. |
ruc | Con o sin DV: 44444401 o 44444401-7. |
limit | De 1 a 200 resultados; por defecto, 50. |
{
"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:
- Buscalo con
GET /v1/emitters?external_id=.... - Si aparece, guardá su
idy seguí con el certificado y el timbrado. - 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 con0).dv: un dígito, que tiene que ser el módulo 11 del RUC. Si no lo es, la respuesta es422 emitters.dv_mismatch(el SIFEN lo rechazaría con1253).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": []
}
}'| Campo | Uso |
|---|---|
tipo_contribuyente | Obligatorio: 1 persona física, 2 persona jurídica (iTipCont, entra en el CDC). |
tipo_regimen | Opcional: código de 1 a 8 (cTipReg). |
nombre_fantasia | Opcional: de 4 a 255 caracteres. |
actividades_economicas | Obligatorio: de 1 a 9, cada una con codigo y descripcion. |
domicilio | Obligatorio: dirección del local que emite. |
establecimientos | Opcional: 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 (0si la dirección no tiene numeración).complemento_1ycomplemento_2, opcionales.departamento, obligatorio: se valida contra el catálogo oficial y KilaSifen guarda su descripción oficial.descripcion_departamentoes opcional, pero si la mandás tiene que coincidir con el código.distritoydescripcion_distrito, opcionales; van juntos.ciudadydescripcion_ciudad, obligatorios.telefono(de 6 a 15 caracteres, con prefijo) yemail, 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
1255a1260. - Una actividad económica que no es del RUC se rechaza con
1261o1262. - 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_idadmite de 1 a 4 dígitos, entre 1 y 9999, y se guarda con cuatro (1→0001). Un0responde422 emitters.csc_id_invalid.- Hacen falta los dos. Sin CSC o sin
csc_idno se puede armar el QR: el documento quedafailedconemitters.csc_requiredy el KuDE responde409 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
2501si el CSC no está vigente en la fecha de emisión (NT 10).
Comprobar preparación
GET /v1/emitters/{emitter_id}/healthRequiere tenant:read.
{
"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_certificatedice si hay un certificado activo, aunque esté vencido. Para saber si vale, mirácertificate_valid_until.has_active_stampingystamping_numberse evalúan parastamping_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. healthno informa el CSC ni el perfil fiscal. Para eso, mirácsc_configuredyfiscal_profile_completeenGET /v1/emitters/{emitter_id}.
Desactivar
POST /v1/emitters/{emitter_id}/deactivateAlcanza 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
PATCHdelegal_nameo defiscal_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).