Documentación de la API REST

Generación y gestión de

Documentos Digitales y Electrónicos

Octubre 2022

Versión 2.3

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 1
Asunción - Paraguay
Contenido
Autenticación ...................................................................................................................................... 3
POST /api/v2/token/ ........................................................................................................................... 3
POST /api/v2/refresh/ ......................................................................................................................... 5
Documento individual ......................................................................................................................... 8
POST /api/v2/documentos-electronicos/ ............................................................................................ 8
GET /api/v2/documentos-electronicos/............................................................................................. 12
Lote de Documentos ......................................................................................................................... 15
POST /api/v2/lote-documentos-electronicos/ .................................................................................. 15
GET /api/v2/lote-documentos-electronicos/ ..................................................................................... 19
Lote de Documentos Instantáneos ................................................................................................... 26
POST /api/v2/lote-de-instantaneos/ ................................................................................................ 26
Notificaciones .................................................................................................................................... 30
POST /api/v2/notificaciones/ ............................................................................................................ 30
Objetos DE ......................................................................................................................................... 33
Objeto JSON DE ................................................................................................................................. 33
Objeto XML DE ................................................................................................................................... 34
Control de cambios............................................................................................................................ 35

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 2
Asunción - Paraguay
 API versión 2
A continuación, se detallan las distintas rutas disponibles, con sus respectivas cabeceras y
cuerpos, para realizar las peticiones correspondientes.

Autenticación

POST /api/v2/token/
Genera un JSON Web Token para la autenticación.

URL del recurso

https://factury.com.py/api/v2/token/

Cabecera de la petición

KEY VALUE

Content-Type application/json

Accept application/json

Cuerpo de la petición

KEY DATA TYPE VALUE

username String Usuario

password String Contraseña

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 3
Asunción - Paraguay
RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

access String Token que dura 5 minutos en expirar.

refresh String El valor de este token servirá para enviar

petición de refrescar el token mediante
otro Endpoint habilitado: /api/v2/refresh/

RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si el JSON no incluye las claves “username” o “password”
en el JSON)

401 Unauthorized (si los valores de “username” o “password” no

corresponden a un usuario válido/registrado)

EJEMPLO

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 4
Asunción - Paraguay
POST /api/v2/refresh/
Permite refrescar el token de acceso, una vez expirado (pasados los 5 minutos de haber
obtenido el Token de acceso).

URL del recurso

https://factury.com.py/api/v2/refresh/

Cabecera de la petición

KEY VALUE

Content-Type application/json

Accept application/json

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 5
Asunción - Paraguay
Cuerpo de la petición

KEY DATA TYPE VALUE

refresh String Valor del token “refresh” generado previamente

con la petición al endpoint /api/v2/token (que
sirve por 24 hs.). pasado ese tiempo, se debe
volver a invocar al endpoint /api/v2/token con el
usuario y contraseña correspondientes.

RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

access String Token regenerado que dura otros 5

minutos. Pasado ese tiempo, se debe
volver a refrescar el Token.

RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si el JSON no incluye la clave “refresh” en el JSON)

401 Unauthorized (si el valor de “refresh” no corresponden a un token válido)

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 6
Asunción - Paraguay
EJEMPLO

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 7
Asunción - Paraguay
Documento individual

POST /api/v2/documentos-electronicos/
ATENCIÓN: Favor consultar disponibilidad de este servicio pues este endpoint solo está
disponible en el ambiente TEST de la SET, no está disponible en el ambiente de Producción, por
lo que recomendamos utilizarlo solo para pruebas

Recibe en formato json las claves y valores según lo requerido por la SET para la emisión y
posterior gestión de documentos digitales o electrónicos a partir de los mismos.

URL del recurso

https://factury.com.py/api/v2/documentos-electronicos/

Cabecera de la petición

KEY VALUE

Content-Type application/json

Accept application/json

Authentication “Bearer ” + Token

Cuerpo de la petición

PAYLOAD DETALLES

JSON OBJECT Objeto JSON individual. Referirse a la sección Objeto JSON DE

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 8
Asunción - Paraguay
RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

estado_proceso String Puede indicar que se procesó

correctamente con el mensaje “OK” o
“ERROR” en su defecto, para indicar que no
se pudo procesar correctamente.

observaciones String En caso de que el estado de proceso sea

“OK”, devolvería texto vacío, en cambio, si
el estado de proceso sea “Error”, entonces
devolvería detalles del motivo por el cual
no se pudo procesar correctamente.

detalles_documento JSON Se devuelven los siguientes datos del

documento:

cdc: código de control, generado por el

sistema del emisor.

estado: Aprobado, Aprobado con

Observación, Rechazado.

observaciones: Para los casos de

“Aprobado con Observación” y “Rechazado”,
serían los detalles asociados.

url_xml: enlace para descargar el xml del

documento electrónico generado y firmado
por la SET.

url_kude: enlace para descargar el PDF

(Kude) del documento correspondiente.

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 9
Asunción - Paraguay
RESPUESTAS NO SATISFACTORIAS – ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si el contenido no corresponde a un JSON válido)

401 Unauthorized (si en la cabecera de la petición, no se incluye el key

“Authorization” con el valor “Bearer Token_generado”)

500 Internal Server Error

EJEMPLO

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 10
Asunción - Paraguay
Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 11
Asunción - Paraguay
GET /api/v2/documentos-electronicos/
Permite obtener el estado del documento digital o electrónico a partir del CDC, como
también URLs para descargar el XML firmado y el PDF del KuDE.

URL del recurso

https://factury.com.py/api/v2/documentos-electronicos/{CDC}?formato={formato}

Cabecera de la petición

KEY VALUE

Content-Type application/json

Accept application/json

Authentication “Bearer ” + Token

Parámetros de la URL de la petición

KEY DATA TYPE VALUE

cdc String Código de control del documento.

formato String Opcional. Permite obtener el documento en

formato XML o PDF.

Valores esperados: xml, pdf

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 12
Asunción - Paraguay
RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

cdc String Código de control del documento.

cod_estado String Corresponde al código del estado del

documento. Los posibles valores son: “EPI”,
“GEN”, “EMI”, “EPE”, “APR”, “APO”, “REC”,
“ANU”

estado String Corresponde a la descripción del estado de

cada documento. Los posibles valores
correspondientes al código del estado son:
“Error Pre-Validación Nivel 1”, “Generado”
“Emitido”, “Error Pre-Validación Nivel 2”,
“Aprobado”, “Aprobado con Observaciones”,
“Rechazado”, “Anulado”

observaciones String Pueden ocurrir tres cosas:

1) El documento fue aprobado y no tiene

ninguna observación de parte de la SET,
por tanto, devolvería texto vacío.

2) El documento fue aprobado, pero la SET

devuelve alguna observación.

3) El documento fue rechazado, por tanto,

devuelve el código del error con su
respectivo mensaje.

nro_lote_set Integer Nro. de lote de acuerdo con el protocolo de

recepción del SIFEN.
url_xml String Enlace para descargar el XML Firmado del
documento.
url_kude String Enlace para descargar el PDF del
documento.

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 13
Asunción - Paraguay
RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si no se coloca el CDC en la URL como identificador del
recurso o es un valor inválido para el CDC o no es CDC válido)

401 Unauthorized (si en la cabecera de la petición, no se incluye el key

“Authorization” con el valor “Bearer Token_generado”)

EJEMPLO

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 14
Asunción - Paraguay
Lote de Documentos

POST /api/v2/lote-documentos-electronicos/
Recibe los datos que conforman los documentos (facturas, notas de crédito, notas de
débito, autofactura, notas de remisión) para la generación de los documentos digitales o
electrónicos correspondientes a partir de los mismos.

URL del recurso

https://factury.com.py/api/v2/lote-documentos-electronicos/

Cabecera de la petición

KEY VALUE

Content-Type application/json

(soporta JSON o XML) application/xml

Accept application/json

(Soporta JSON o XML) application/xml

Authentication “Bearer ” + Token

Cuerpo de la petición (Content-Type: application/json)

KEY DATA TYPE VALUE

data JSON Array Array de objetos JSON DE. Referirse a la

sección Objeto JSON DE

Cuerpo de la petición (Content-Type: application/xml)

Documento XML generado con la estructura definida en el MT de SIFEN. Referirse a la sección

Objeto XML DE

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 15
Asunción - Paraguay
RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

id_proceso Integer Con este identificador único de proceso, se

podrá verificar posteriormente el estado de
la firma de los documentos enviados en el
lote. Si ocurriese algún error al momento
de procesar, devolvería 0.

mensaje String Puede indicar que se recibió la data

correctamente y se inició el proceso de
generación de documentos electrónicos
con el mensaje “OK” o en su defecto,
indicar el error que se produjo durante el
procesamiento.

RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si el contenido no corresponde a un JSON válido)

401 Unauthorized (si en la cabecera de la petición, no se incluye el key

“Authorization” con el valor “Bearer Token_generado”)

500 Internal Server Error

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 16
Asunción - Paraguay
EJEMPLOS

Para el caso de enviar en Formato JSON:

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 17
Asunción - Paraguay
Para el caso de enviar en Formato XML:

Envío de un único documento:

Envío de más de un documento:

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 18
Asunción - Paraguay
GET /api/v2/lote-documentos-electronicos/
Permite obtener tanto el estado de los documentos digitales o electrónicos, como también
el lote de documentos digitales o electrónicos en formato XML que fueron generados,
firmados y fiscalizados por la SET.

URL del recurso

https://factury.com.py/api/v2/lote-documentos-electronicos/

Cabecera de la petición

KEY VALUE

Content-Type application/json

(soporta JSON o XML) application/xml

Accept application/json

(Soporta JSON o XML) application/xml

Authentication “Bearer ” + Token

Parámetros de la petición

KEY DATA TYPE VALUE

id_proceso Integer Código del proceso que identifica al lote.

tipo String Los posibles valores son:

“json”: En caso de que se desee obtener el

detalle de los documentos electrónicos
procesados

“zip”: para obtener el lote de archivos XML

que fueron generados, firmados y enviados
a la SET, siempre y cuando ya se encuentre
disponible.

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 19
Asunción - Paraguay
 “payload”: para obtener el json que
originalmente se envió en el cuerpo de la
petición de generación de lote de
documentos electrónicos.

“xml”: para obtener los resultados en

formato XML, en el caso que los
parámetros de la cabecera de la petición
sean Content-Type: application/xml y
Accept: application/xml respectivamente.

RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

cantidad_documentos Integer Cantidad de documentos que se

recibieron/procesaron del JSON enviado.

cantidad_correctos Integer Cantidad de documentos que, al pasar por

el proceso de generación de documentos,
no registraron errores.

cantidad_incorrectos Integer Cantidad de documentos que, al pasar por

el proceso de generación de documentos,
registraron errores.

estado String Informa el estado del lote de documentos,

al momento de la consulta. Los posibles
valores son: “Generando Documentos
Electrónicos”, “Documentos pendientes de
validación”, “Procesando Documentos
Electrónicos”, “Finalizado”, “Finalizado con
errores”. Solamente si el estado es
“Finalizado” se puede descargar el zip de

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 20
Asunción - Paraguay
 documentos XML Firmados enviados a la
SET.

documentos List En caso de que el parámetro tipo sea

“json” o “xml”, devuelve los documentos
electrónicos y otros datos generados por la
SET en dicho formato (especificados en el
siguiente cuadro “Respuesta Detalles”), en
cambio, si el parámetro es “zip”, se
devuelve un string del archivo zip
convertido a base64, que contiene todos
los documentos electrónicos generados y
enviados a la SET.

Documentos

KEY DATA TYPE VALUE

cdc String Código de control de cada documento

incluido en el lote

nro_lote_set Integer Nro. de lote de acuerdo al protocolo de

recepción del SIFEN.

estado String Corresponde al estado de cada documento.

Los posibles valores son: “Pendiente”,
“Error de Pre-Validación” “Aprobado”,
“Aprobado con Observaciones”,
“Rechazado”.

protocolo Integer Representa el protocolo de autorización del

documento electrónico. En caso de que no
se haya aprobado, su valor es 0.

observaciones String Pueden ocurrir tres cosas:

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 21
Asunción - Paraguay
 1) El documento fue aprobado y no tiene
ninguna observación de parte de la SET,
por tanto, devolvería un array vacío.

2) El documento fue aprobado, pero la SET

devuelve una lista de observaciones. En
ese caso, devolvería un array que contiene
los códigos y mensajes correspondientes.

3) El documento fue rechazado, por tanto,

devuelve el código del error con su
respectivo mensaje.

RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si no se envía el parámetro del id_proceso, tiene valor 0 o
bien, el parámetro de filtro del tipo no es válido)

404 Not Found (si no se encuentra el lote de acuerdo al id_proceso enviado

en la petición o no se encontraron documentos generados en el lote
especificado)

401 Unauthorized (si en la cabecera de la petición, no se incluye el key

“Authorization” con el valor “Bearer Token_generado”)

EJEMPLO – OBTENER ESTADO DE VALIDACIÓN DE DOCUMENTOS

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 22
Asunción - Paraguay
EJEMPLO – OBTENER ESTADO DEL LOTE EN XML

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 23
Asunción - Paraguay
EJEMPLO – OBTENER ZIP DE DOCUMENTOS XML FIRMADOS EN BASE 64

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 24
Asunción - Paraguay
Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 25
Asunción - Paraguay
Lote de Documentos Instantáneos

POST /api/v2/lote-de-instantaneos/
Endpoint disponible para lotes de menos de 10 documentos. Se replican las
funcionalidades del servicio lote-documentos-electronicos pero se procesan los
documentos en menos de un minuto. Además se devuelven los cdc en la misma petición

URL del recurso

https://factury.com.py/api/v2/lote-de-instantaneos/

Cabecera de la petición

KEY VALUE

Content-Type application/json

(soporta JSON o XML) application/xml

Accept application/json

(Soporta JSON o XML) application/xml

Authentication “Bearer ” + Token

Cuerpo de la petición (Content-Type: application/json)

KEY DATA TYPE VALUE

data JSON Array Array de objetos JSON DE. Referirse a la

sección Objeto JSON DE

Cuerpo de la petición (Content-Type: application/xml)

Documento XML generado con la estructura definida en el MT de SIFEN. Referirse a la sección

Objeto XML DE

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 26
Asunción - Paraguay
RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

id_proceso Integer Con este identificador único de proceso, se

podrá verificar posteriormente el estado de
la firma de los documentos enviados en el
lote. Si ocurriese algún error al momento
de procesar, devolvería 0.

mensaje String Puede indicar que se recibió la data

correctamente y se inició el proceso de
generación de documentos electrónicos
con el mensaje “OK” o en su defecto,
indicar el error que se produjo durante el
procesamiento.

documentos List Devuelve la lista de documentos

electrónicos procesados (especificados en
el cuadro “Respuesta Detalles”).

RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si el contenido no corresponde a un JSON válido)

401 Unauthorized (si en la cabecera de la petición, no se incluye el key

“Authorization” con el valor “Bearer Token_generado”)

500 Internal Server Error

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 27
Asunción - Paraguay
EJEMPLOS

Para el caso de enviar en Formato JSON:

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 28
Asunción - Paraguay
Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 29
Asunción - Paraguay
Notificaciones

POST /api/v2/notificaciones/
Recibe el CDC del Documento Electrónico y el correo del remitente para enviarle la
notificación de la emisión correspondiente.

Nota importante: Este endpoint en particular es opcional y desarrollado a medida con

cada cliente.

URL del recurso

https://factury.com.py/api/v2/notificaciones/

Cabecera de la petición

KEY VALUE

Content-Type application/json

Accept application/json

Authentication “Bearer ” + Token

Cuerpo de la petición

KEY DATA TYPE VALUE

cdc string CDC del Documento Electrónico al cual se

desea notificar la emisión. OBLIGATORIO

email string Correo electrónico del remitente a notificar.

OPCIONAL

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 30
Asunción - Paraguay
RESPUESTA SATISFACTORIA: 200 OK

KEY DATA TYPE VALUE

mensaje String Indica un mensaje alusivo al resultado del

envío.

RESPUESTAS NO SATISFACTORIAS - ERRORES

HTTP STATUS CODE DESCRIPTION

400 Bad request (si el contenido no corresponde a un JSON válido)

401 Unauthorized (si en la cabecera de la petición, no se incluye el key

“Authorization” con el valor “Bearer Token_generado”)

500 Internal Server Error

EJEMPLO

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 31
Asunción - Paraguay
Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 32
Asunción - Paraguay
Objetos DE

Objeto JSON DE
Las claves corresponden a los campos definidos en el Manual Técnico de la SIFEN, tal cual
están allí definidos (sensible a mayúsculas y minúsculas).

La estructura del JSON deberá reflejar la estructura jerárquica de etiquetas en sus

distintos niveles.

Si no es obligatorio, la etiqueta puede omitirse en el JSON. Si la etiqueta no posee valor

se recomienda no enviarla en el JSON.

Existen claves que corresponden a un valor y otros, a una lista de elementos (clave-valor)
anidados, según la jerarquía definida en el Manual Técnico de la SIFEN.

No es preciso enviar los campos definidos en las secciones AA (Campos que identifican el
formato electrónico XML), A (Campos firmados del Documento Electrónico) ni B (Campos
inherentes a la operación de Documentos electrónicos), descritos en las Págs. 61 y 62 del
Manual Técnico SIFEN (versión 150). Dicho de otro modo, se deben generar a partir de la
sección C (Campos de datos del Timbrado Grupo gTimb) según corresponda a cada tipo de
documento. Pág. 63 en adelante del MT.
Adicionalmente, se podrá obviar enviar los datos del emisor y actividad económica si se
rellena la planilla preparada para el efecto para dar de alta los datos como constantes.

Ejemplo:

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 33
Asunción - Paraguay
Objeto XML DE
El objeto debe seguir las mismas directrices que el manual técnico de la SIFEN y el objeto
JSON pero adicionalmente se debe tener en cuenta las etiquetas contenedoras del xml:

Cuándo se envía un solo documento, éste debe estar contenido en la etiqueta <DE> que a
su vez está contenida en la etiqueta <rDE> Ejemplo:

Si se envía más de un documento, la lista de documentos debe estar contenida en la

etiqueta <rLoteDE> Ejemplo:

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 34
Asunción - Paraguay
Control de cambios
Fecha Versión Descripción

24/06/22 2.1 Lanzamiento versión v2 de la Api

02/09/22 2.2 Aclaración etiqueta inicial esperada Objeto JSON DE

13/10/22 2.3 Se crea la nueva sección Objeto DE

Se aclara el parámetro adicional “formato”disponible en
/api/v2/documentos-electronicos/
Se agrega el nuevo endpoint Lote de Documentos Instantáneos
Se modifican los estados del proceso disponibles en GET /api/v2/lote-
documentos-electronicos/

Santa Rosa N° 591 c/ Avda. España. Tel.: (595 21) 621 480 35
Asunción - Paraguay