Skip to main content

Documentación de la API

Introducción​

A través de esta documentación, se busca garantizar que los integradores comprendan claramente el formato requerido para los archivos JSON y las rutas necesarias para interactuar con la API, asegurando una implementación eficiente y conforme a los requerimientos del sistema.

Esta sección cubre:

  1. Emisión de Documentos Electrónicos
    Explicación detallada de la estructura JSON requerida para emitir documentos de forma síncrona o en lote (asíncrona).

  2. Consulta de Lotes y Documentos
    Procedimientos para consultar el estado de un lote o un documento utilizando su CDC (Código de Control).

  3. Consulta de RUC
    Proceso para validar datos de contribuyentes mediante la consulta de su RUC.

  4. Envío de Eventos
    Instrucciones para gestionar eventos específicos como cancelación, inutilización, nominación, o modificación de datos relacionados al transporte.

Autenticación​

La API de DTEpy utiliza un sistema de autenticación basado en tokens para garantizar la seguridad y el control de acceso. A continuación, se describe cómo obtener y utilizar el token:

  1. Obtención del Token
    Para obtener un token de acceso, es necesario que el usuario esté registrado en la plataforma web de DTEpy. Una vez registrado y autenticado en el sistema, se puede acceder al token desde la pestaña "Tokens" dentro del menú de Configuraciones. Este proceso se detalla en el apartado "Crear una cuenta" de este manual, donde se explican los pasos necesarios para registrarse y gestionar el token.

  2. Uso del Token en las Peticiones
    El token debe incluirse como parte de las solicitudes enviadas a los endpoints de la API para garantizar la autenticación. Hay dos formas de pasar el token:

    1. En los Headers de la Petición:

    • El token debe enviarse utilizando la clave x-access-token en los encabezados de la solicitud.

    • Ejemplo de encabezado:

      shell
      curl -X 'POST' \
      'https://test.globeinformatica.com.py/documentoset' \
      -H 'Content-Type: application/json' \
      -H 'x-access-token: eyJhbGciOiJIUzI1NiIs'

    2. En el Cuerpo (Body) de la Petición:

    • Como alternativa, el token también puede incluirse dentro del atributo token en el cuerpo de la solicitud (body).

    • Ejemplo de uso en el body:

      json
      {
      "token": "eyJhbGciOiJIUzI1NiIs",
      "otros-datos": "valor"
      }

Consideraciones Importantes

  • Es obligatorio autenticar cada solicitud antes de interactuar con los endpoints de la API. Si no se incluye un token válido, la solicitud será rechazada con un error de autorización.
  • Se recomienda utilizar siempre el método del header x-access-token, ya que es más seguro y sigue las mejores prácticas de autenticación.

Ambientes de Uso​

https://test.globeinformatica.com.py

Endpoints Principales:​

POST /documentoset (url para trasmitir documentos síncrono)

Para la emisión de un documento electrónico, es necesario estructurar el JSON según el formato especificado para cada tipo de documento que se desea enviar. Este formato puede ser utilizado tanto para envíos individuales (sincrónicos) como para envíos por lote, envolviendo cada JSON como un elemento dentro de un arreglo. A continuación, se detalla el formato base y su utilización en el endpoint correspondiente.

json
{
    "tipoDocumento": 1,
    "codigoSeguridadAleatorio": 123456789,
    "token": null,
    "pin": "EBA762",
    "tipoEmision": 1,
    "establecimiento": "001",
    "punto": "001",
    "numero": "0000001",
    "serie": "",
    "fecha": "2022-08-14T10:11:00",
    "tipoTransaccion": 1,
    "tipoImpuesto": 1,
    "moneda": "PYG",
    "cambio": 6270,
    "envio_pend": 1,
    "cdc": "12345678901234567890123456789012345678901234",
    "id": 10,
    "obligaciones": [
        {
            "codigo": 211,
            "descripcion": "IMPUESTO AL VALOR AGREGADO"
        },
        {
            "codigo": 700,
            "descripcion": "IRE GENERAL"
        }
    ],
    "dncp": {
        "modalidad": "AB",
        "entidad": 1,
        "año": 25,
        "secuencia": 1234567,
        "fecha": "2025-01-01"
    },
    "factura": {
        "presencia": 1
    },
    "cliente": {
        "razonSocial": "JUAN PEREZ",
        "nombreFantasia": "EMPRESA S.A.",
        "email": "juanperez@hotmail.com",
        "contribuyente": true,
        "tipoContribuyente": 1,
        "tipoOperacion": 2,
        "ruc": "1111111-6",
        "documentoTipo": 1,
        "documentoNumero": "1111111",
        "direccion": "AVDA. MCAL. LOPEZ",
        "numeroCasa": 1250,
        "pais": "PRY",
        "departamento": 1,
        "distrito": 1,
        "ciudad": 1
    },
    "usuario": {
        "nombre": "JUAN GONZALEZ",
        "cargo": "CAJERO",
        "documentoTipo": 1,
        "documentoNumero": "1111111"
    },
    "condicion": {
        "tipo": 1,
        "entregas": [
            {
                "tipo": 1,
                "monto": 150000,
                "moneda": "PYG",
                "cambio": 6270
            },
            {
                "tipo": 2,
                "monto": 150000,
                "moneda": "PYG",
                "cambio": 6270,
                "infoTarjeta": {
                    "tipo": 1,
                    "tipoDescripcion": "VISA",
                    "numero": 1234,
                    "medioPago": 1
                }
            },
            {
                "tipo": 3,
                "monto": 150000,
                "moneda": "PYG",
                "cambio": 6270,
                "infoCheque": {
                    "numeroCheque": 12345678,
                    "banco": "VISION BANCO"
                }
            }
        ],
        "credito": {
            "tipo": 1,
            "plazo": "30 dias",
            "cuotas": 2,
            "montoEntrega": 150000,
            "infocuotas": [
                {
                    "moneda": "PYG",
                    "monto": 150000,
                    "vencimiento": "2021-10-30"
                },
                {
                    "moneda": "PYG",
                    "monto": 150000,
                    "vencimiento": "2021-11-30"
                }
            ]
        }
    },
    "items": [
        {
            "codigo": "A-001",
            "descripcion": "PRODUCTO Y/O SERVICIO 001",
            "observacion": "",
            "unidadMedida": 77,
            "cantidad": 2,
            "precioUnitario": 150000,
            "descuento": 10000,
            "ivaTipo": 1,
            "ivaBase": 100,
            "iva": 10
        },
        {
            "codigo": "A-001",
            "descripcion": "PRODUCTO Y/O SERVICIO 002",
            "observacion": "",
            "unidadMedida": 77,
            "cantidad": 2,
            "precioUnitario": 150000,
            "descuento": 0,
            "ivaTipo": 1,
            "ivaBase": 100,
            "iva": 10
        }
    ],
    "documentoAsociado": null
}

Respuestas

Las respuestas de 'Aprobado' y 'Rechazado' son mensajes proporcionados directamente por la API de SIFEN. Sin embargo, como se muestra en el tercer apartado, puede recibir el formato de mensaje de error identificado por la API de DTEpy, que le brindara detalles sobre posibles inconvenientes en la estructura del JSON.

json Status: 200
{
    "ns2:rRetEnviDe": {
        "$": {
            "xmlns:ns2": "http://ekuatia.set.gov.py/sifen/xsd"
        },
        "ns2:rProtDe": {
            "ns2:Id": "12345678901234567890123456789012345678901234",
            "ns2:dFecProc": "2023-07-29T08:39:44-04:00",
            "ns2:dDigVal": "d2h1V3hPYWZTV01leUlVNEpIMFZqRFMrRjVpQkM2RSt5UG9rVTkzajhzaz0=",
            "ns2:dEstRes": "Aprobado",
            "ns2:dProtAut": "39837276",
            "ns2:gResProc": {
                "ns2:dCodRes": "0260",
                "ns2:dMsgRes": "Autorización del DE satisfactoria"
            }
        }
    },
    "id": 1
}
POST /documentoset/lotes (url para trasmitir documentos asíncrono - lotes)

El envío asincrónico (lote) permite agrupar hasta 50 documentos JSON en un arreglo, conforme al lo estructurado en el endpoint /documentoset, para transmitirlos en un único proceso. Al enviar el lote, se recibe un número de lote como confirmación, pero el procesamiento de los documentos es posterior. La API de DTEpy realiza automáticamente la consulta de cada lote emitido y actualiza la información del estado en la base de datos en la nube.

Cuerpo de la solicitud

json
{
  "tipoDocumento": 1,
  "id": 1,
  "detalle": [
    {
      "JSON DEL DOCUMENTO": "EJ. 001-001-0000001"
    },
    {
      "JSON DEL DOCUMENTO": "EJ. 001-001-0000002"
    },
    {
      "JSON DEL DOCUMENTO": "... HASTA 50 DOCUMENTOS"
    }
  ]
}

Respuestas

json Status: 200
{
    "ns2:rResEnviLoteDe": {
        "$": {
            "xmlns:ns2": "http://ekuatia.set.gov.py/sifen/xsd"
        },
        "ns2:dFecProc": "2019-06-03T12:00:00",
        "ns2:dCodRes": "0300",
        "ns2:dMsgRes": "Lote recibido con éxito",
        "ns2:dProtConsLote": "123456789012345678",
        "ns2:dTpoProces": "32"
    }
}
POST /documentoset/consulta (url para consultar documentos por CDC)

Permite consultar el estado de un documento electrónico enviado al SIFEN utilizando su Código de Control (CDC). Este proceso es útil para verificar la aprobación o el rechazo del documento directamente en el sistema del SIFEN. A continuación, se muestra un ejemplo de la estructura del JSON necesario para realizar la consulta.

Cuerpo de la solicitud

json
{
    "id": 1,
    "cdc": "12345678901234567890123456789012345678901234",
    "tipoDocumento": 1
}

Respuestas

json Status: 200
{
    "ns2:rEnviConsDeResponse": {
        "$": {
            "xmlns:ns2": "http://ekuatia.set.gov.py/sifen/xsd"
        },
        "ns2:dFecProc": "2023-08-10T15:14:26-04:00",
        "ns2:dCodRes": "0422",
        "ns2:dMsgRes": "CDC encontrado",
        "ns2:xContenDE": "<?xml aqui devuelve la cadena completa del xml del DE enviado y la cadena de eventos de cancelacion o inutilizacion si los hubiere >"
    },
    "id": 44
}
POST /documentoset/consultalote (para consultar documentos por número de lote)

Se utiliza para consultar el estado de un lote enviado. Este lote puede contener uno o varios documentos electrónicos, y la respuesta incluirá el estado individual de cada documento contenido en el lote. Esto permite verificar el procesamiento completo del lote y obtener detalles sobre la aprobación o el rechazo de cada documento.

Cuerpo de la solicitud

json
{
    "id": 1,
    "numlote": "123456789012345678",
    "tipoDocumento": 1
}

Respuestas

json Status: 200
{
    "ns2:rResEnviConsLoteDe": {
        "$": {
            "xmlns:ns2": "http://ekuatia.set.gov.py/sifen/xsd"
        },
        "ns2:dFecProc": "2019-06-03T12:00:00",
        "ns2:dCodResLot": "0362",
        "ns2:dMsgResLot": "Procesamiento de lote {159204793632399660} concluido",
        "ns2:gResProcLote": [
            {
                "ns2:id": "12345678901234567890123456789012345678901234",
                "ns2:dEstRes": "Aprobado",
                "ns2:dProtAut": "12345678",
                "ns2:gResProc": {
                    "ns2:dCodRes": "0422",
                    "ns2:dMsgRes": "CDC encontrado"
                }
            },
            {
                "ns2:id": "11111111112222222222333333333344444444445555",
                "ns2:dEstRes": "Rechazado",
                "ns2:gResProc": {
                    "ns2:dCodRes": "0160",
                    "ns2:dMsgRes": "aqui va el motivo del error por rechazo"
                }
            }
        ]
    },
    "id": 10
}
{
    "ns2:rResEnviConsLoteDe": {
        "$": {
            "xmlns:ns2": "http://ekuatia.set.gov.py/sifen/xsd"
        },
        "ns2:dFecProc": "2019-06-03T12:00:00",
        "ns2:dCodResLot": "0362",
        "ns2:dMsgResLot": "Procesamiento de lote {159204793632399660} concluido",
        "ns2:gResProcLote": {
            "ns2:id": "12345678901234567890123456789012345678901234",
            "ns2:dEstRes": "Aprobado",
            "ns2:dProtAut": "12345678",
            "ns2:gResProc": {
                "ns2:dCodRes": "0422",
                "ns2:dMsgRes": "CDC encontrado"
            }
        }
    },
    "id": 10
}
POST https://ruc.globeinformatica.com.py/api/dnit (url para consultar RUC de clientes)

permite consultar los datos de un cliente utilizando su RUC (sin el dígito verificador). Esta consulta determina si el cliente es contribuyente, devolviendo información relevante directamente desde el SIFEN. Además, con los datos de la respuesta json el usuario podra insertar automáticamente los datos del cliente como un nuevo registro en su base de datos, en caso de que este no se encuentre previamente registrado en su sistema ERP. Esto agiliza el proceso de gestión de clientes y asegura que los datos estén actualizados y sincronizados.

Cuerpo de la solicitud

json
{
    "ruc": "4001413"
}

Respuestas

json Status: 200
[
    {
        "ruc": "4001413",
        "nombre": "ALVAREZ, ARNALDO FABIAN",
        "dv": "4",
        "ruc_ant": "AAAR840300D",
        "estado": "ACTIVO"
    }
]
POST /documentoset/cancelacion (url para cancelar un DTE)

Este es un evento solicitado por el emisor, ocurre cuando el comprobante es emitido sin errores y transmitido y aprobado por el SIFEN se convierte en un DTE, sin embargo, por algún motivo no se concreta la transacción. El emisor electrónico puede

PRECAUCIÓN

No podra cancelar un DTE pasada las 48hs despues de su aprobación.

Cuerpo de la solicitud

json
{
  "id": 1,
  "cdc": "12345678901234567890123456789012345678901234",
  "motivo": "SE ANULA POR ALGUN ERROR",
  "tipoDocumento": 1
}

Respuestas

json Status: 200
{
    "ns2:rRetEnviEventoDe": {
        "$": {
            "xmlns:ns2": "http://ekuatia.set.gov.py/sifen/xsd"
        },
        "ns2:dFecProc": "2019-06-03T12:00:00",
        "ns2:gResProcEVe": {
            "ns2:dEstRes": "Aprobado",
            "ns2:dProtAut": "935252",
            "ns2:id": "32",
            "ns2:gResProc": {
                "ns2:dCodRes": "0600",
                "ns2:dMsgRes": "Evento registrado correctamente"
            }
        }
    },
    "id": 3
}
POST /documentoset/inutilizacion (url para inutilizar un DE o rango de números)

aqui va el contenido

POST /documentoset/nominacion (url para nominar un documento cliente innominado)

aqui va el contenido

POST /documentoset/datostransporte (url para actualizar datos de una remisión)

aqui va el contenido

Otros Endpoints:​

POST /documentoset/consultadocs

aqui va el contenido

POST /documentoset/ultimosdocs

aqui va el contenido

GET /documentoset/getexpiration

aqui va el contenido