ISFactura
Etapa productiva

Credenciales y JWT

Todo lo que se prueba en la documentación se ejecuta contra el sandbox con la cuenta con la que ingresaste al portal. En producción esa cuenta no interviene: la petición viaja con un JWT que genera tu propia integración a partir de las credenciales que se te entregan. Este capítulo explica cómo se obtiene ese token, qué se le puede poner dentro y para qué sirve lo que le pongas.

1 · Cómo se obtienen las credenciales

Las credenciales no se generan desde el portal. Una vez tu solicitud de desarrollador queda autorizada, InSoft te entrega el juego de credenciales de tu integración: el identificador de la integración, su usuario y su contraseña. Con eso —y con nada más— tu software genera los tokens que necesite.

Son personales e intransferibles

Las credenciales identifican a tu integración y responden por lo que se emita con ellas. No se comparten con terceros, no se publican en un repositorio ni se incrustan en una aplicación que se distribuya al usuario final: quien las tenga puede emitir en nombre de los emisores que tengas autorizados. Guárdalas donde guardas el resto de tus secretos de servidor, y pide su reemplazo en cuanto sospeches que se filtraron.

La URL de producción se entrega junto con las credenciales. Las rutas que documenta el portal son las mismas: lo único que cambia entre el sandbox y producción es esa base y el token con el que se firma la petición.

2 · Generar el JWT

El token se pide con una sola petición. En el cuerpo van dos objetos: integracion —tus credenciales— y origen, que es lo que va a quedar marcado en todo documento emitido con ese token.

{
   "integracion": {
      "tercero": "<el que te entregamos>",
      "usuario": "<el que te entregamos>",
      "password": "<la que te entregamos>"
   },
   "origen": {
      "nitemisor": "900123456",
      "areatrabajo": "SEDE-NORTE",
      "itercero": "CLI-00412",
      "iusuario": "jperez",
      "iusuarioso": "jperez",
      "iequipo": 14,
      "pid": 8321,
      "iapp": "<el que te entregamos>",
      "version": "3010020019"
   }
}

La respuesta trae el token firmado y una copia de lo que quedó dentro de él, sin la contraseña. Ese token es el que viaja en la cabecera de cada petición:

Authorization: Bearer <el token que devolvió la petición>
OperaciónQué hace
POST /api/autorizacionGenera un JWT nuevo. Se envía el usuario y la contraseña de la integración junto con los datos de origen, y responde el token firmado.
GET /api/autorizacion/{token}Verifica un JWT y devuelve lo que lleva dentro, sin la contraseña. Es la forma de comprobar que un token sigue siendo válido antes de usarlo.
PUT /api/autorizacion/{token}Renueva un JWT que sigue vigente conservando su identificador, de modo que el mismo origen no cambia de identidad al renovarse.
DELETE /api/autorizacion/{token}Revoca un JWT. Es lo que se usa cuando un equipo sale de servicio o cuando se cierra la sesión de un punto de trabajo.
El token vence, y conviene renovarlo antes

Cada credencial tiene su propia vigencia, acordada al entregarla. Pasada esa vigencia toda petición responde 401. Lo natural es renovar por tiempo, no por error: guarda la fecha de vencimiento que devuelve la respuesta y pide el token nuevo antes de llegar a ella, en lugar de esperar a que una emisión falle para descubrirlo.

3 · Los datos de origen

El bloque origen es la parte que más rendimiento le saca a la credencial. Queda dentro del token, y de ahí pasa a cada documento que se emita con él: no lo repites en cada petición, no altera el contenido del documento y no lo ve la DIAN. Es tuyo, y sirve para responder después preguntas de tu propia operación —de qué sede salió esta factura, qué usuario la hizo, con qué versión de mi software—.

CampoTipoQué identifica
nitemisor *stringIdentificación del emisor en cuyo nombre se emite. Tiene que ser uno de los que tu integración quedó autorizada a emitir: la petición se rechaza si no coincide.
areatrabajo stringEl punto de trabajo desde el que se emite: una sede, una caja, una sucursal, una bodega. Es el corte más útil para agrupar después lo emitido.
itercero stringEl tercero de tu propia operación al que corresponde la emisión, con el identificador que uses en tu sistema.
iusuario stringEl usuario de tu aplicación que está emitiendo, con tu propio identificador.
iusuarioso stringEl usuario del sistema operativo desde el que corre tu aplicación. Distingue quién opera la máquina de quién inició sesión en tu software.
iequipo numberEl equipo desde el que se emite, con el número que uses para inventariarlos.
pid numberEl proceso que emite. Sirve para separar instancias que corren a la vez en el mismo equipo.
iapp stringLa aplicación que emite, con el código que InSoft te entrega junto con las credenciales.
version stringLa versión de esa aplicación. Es lo que permite saber después si un documento salió de una versión que ya se corrigió.

Todos son opcionales salvo nitemisor. Lo que no envíes simplemente no queda marcado: no hay valor por defecto que se invente por ti.

4 · Un token por origen, y tantos como necesites

Con las mismas credenciales puedes generar todos los JWT que quieras, cada uno con su propio bloque de origen. Es la forma prevista de repartir la integración: un token por sede, por caja, por instalación o por servicio, y cada uno emitiendo con su propia marca.

  • Reparte, no compartas Genera el token en tu servidor y entrégalo ya firmado a cada punto que emite. Lo que se distribuye es el token; las credenciales con las que se generó se quedan donde tú las controlas.
  • Un origen distinto por cada cosa que quieras distinguir después El corte que no marques al emitir no se puede reconstruir más tarde. Si vas a querer saber de qué caja salió una factura, esa caja tiene que estar en el areatrabajo del token con el que se emitió.
  • Revoca lo que deja de operar Un equipo que sale de servicio deja su token revocado, no vencido. Es la diferencia entre cerrar la puerta y esperar a que se cierre sola.

5 · La cabecera Authorization en cada ficha

Todas las fichas del portal documentan la misma cabecera Authorization: Bearer …, y en las dos etapas es la misma cabecera con el mismo formato. Lo que cambia es quién la pone:

  • En el sandbox la pone el portal por ti, con la sesión con la que ingresaste. No tienes que hacer nada: cada ejecución la renueva antes de enviar.
  • En producción la pones tú, con el JWT de este capítulo. La sesión del portal no interviene: tu integración no se autentica contra el portal, se autentica con su credencial.

Por eso una integración escrita contra el sandbox pasa a producción cambiando dos cosas: la URL base y el token. El cuerpo, las rutas y las respuestas son los mismos.