Autenticación

TeFacturo utiliza autenticación basada en JWT (JSON Web Tokens). Cada petición a la API debe incluir un token válido en el header Authorization.

Cómo funciona

Envías tus credenciales (ruc, email, clave) al endpoint de login.

Recibes un c2uToken (JWT) válido por 8 horas.

Incluyes el token en el header Authorization: Bearer {c2uToken} de cada petición.

Antes de que expire, solicitas un nuevo token con las mismas credenciales.

Endpoint de autenticación

POSThttps://jarvis.tefacturo.pe/tokenapi/secure/v2/login/token

Petición completa:

POST https://jarvis.tefacturo.pe/tokenapi/secure/v2/login/token
Content-Type: application/json

{
    "aplicacion": {
        "codigo": "1"
    },
    "clave": "{{CLAVE}}",
    "mail": "{{USUARIO}}",
    "ruc": {{RUC}}
}

Respuesta exitosa (200 OK):

Response 200 OK

HTTP/1.1 200 OK
Content-Type: application/json

{
    "c2uToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIyMDEyMzQ1Njc4OSIsIm1haWwiOiJ1c3VhcmlvQGVtcHJlc2EuY29tIiwiaWF0IjoxNzA1MzA0MDAwLCJleHAiOjE3MDUzMzI4MDB9.abc123...",
    "fechaExpiracion": "2025-01-15T08:00:00.000+00:00",
    "ruc": "20123456789",
    "razonSocial": "MI EMPRESA S.A.C.",
    "estado": "ACTIVO"
}

Expiración y renovación del token

Duración del token

Cada token JWT tiene una validez de 8 horas desde el momento de su generación. El campo fechaExpiracion en la respuesta indica la fecha y hora exacta de expiración.

Para cuentas de prueba del portal de documentación, aplica renovación operativa cada 1 hora.

Estrategia de renovación

Recomendamos renovar el token 15 minutos antes de su expiración para evitar interrupciones. Implementa una lógica que verifique la fecha de expiración antes de cada llamada a la API.

Estrategia de renovación

// Pseudocódigo: Estrategia de renovación de token

let token = null;
let tokenExpiry = null;

async function getValidToken() {
    const now = new Date();
    const bufferMs = 15 * 60 * 1000; // 15 minutos de margen

    if (!token || !tokenExpiry || now.getTime() > tokenExpiry - bufferMs) {
        const response = await fetch(
            "https://jarvis.tefacturo.pe/tokenapi/secure/v2/login/token",
            {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    aplicacion: { codigo: "1" },
                    clave: process.env.TEFACTURO_CLAVE,
                    mail: process.env.TEFACTURO_MAIL,
                    ruc: Number(process.env.TEFACTURO_RUC)
                })
            }
        );

        const data = await response.json();
        token = data.c2uToken;
        tokenExpiry = new Date(data.fechaExpiracion).getTime();
    }

    return token;
}

Respuestas de error

Estos son los códigos de error más comunes al interactuar con el sistema de autenticación.

401Unauthorized - Credenciales inválidas

Se retorna cuando el email, clave o RUC son incorrectos.

Error 401

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "codigo": "401",
    "mensaje": "Credenciales inválidas. Verifique su email y clave.",
    "detalle": "El email o la clave proporcionados no coinciden con ninguna cuenta activa."
}

403Forbidden - Token expirado o inválido

Se retorna al usar un token que ya expiro o fue manipulado. Genera un nuevo token.

Error 403

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "codigo": "403",
    "mensaje": "Token expirado o inválido.",
    "detalle": "El token JWT ha expirado. Genere un nuevo token usando el endpoint de login."
}

500Internal Server Error

Error interno del servidor. Reintenta la petición después de unos segundos.

Error 500

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
    "codigo": "500",
    "mensaje": "Error interno del servidor.",
    "detalle": "Ocurrió un error inesperado. Intente nuevamente en unos minutos."
}

Buenas prácticas

Almacena el token de forma segura

Nunca expongas el token en el frontend o en URLs. Guárdalo en variables de entorno o almacenamiento seguro del servidor.

Renueva proactivamente

No esperes a recibir un 403 para renovar. Verifica la fecha de expiración antes de cada petición.

No generes tokens innecesarios

Reutiliza el token activo en lugar de generar uno nuevo en cada petición. Para cuentas de prueba del portal docs, renueva cada 1 hora.

Implementa reintentos

Si recibes un 403, genera un nuevo token y reintenta la petición original automáticamente.

Protege tus credenciales

Nunca incluyas el RUC, email o clave en código fuente. Usa variables de entorno.

Campos de autenticación

Campo	Tipo	Requerido	Descripción
`ruc`	number	Si	RUC de 11 dígitos de la empresa emisora. Se envía sin comillas (tipo numérico).
`mail`	string	Si	Correo electrónico registrado en la plataforma Close2u/TeFacturo.
`clave`	string	Si	Contraseña de acceso proporcionada por Close2u.
`aplicacion.codigo`	string	Si	Código de la aplicación. Usar siempre "1" para la API de facturación.
`c2uToken`	string	-	Token JWT retornado por el endpoint de login. Válido por 8 horas.

Quickstart Siguiente: Emitir Factura