Conceptos

InercIA APIs es una plataforma donde tu empresa contrata servicios por API. Antes de integrar, conviene tener claros estos términos:

Empresa

Tu cuenta, registrada con tu RUC. Todos los usuarios y suscripciones cuelgan de ella.

API

Un servicio que se vende por separado (por ejemplo, la API WhatsApp).

Plan

Precio, vigencia (días) y reglas de uso de una API: consumo mensual, solicitudes por minuto, tokens permitidos y si incluye producción.

Suscripción

La relación entre tu empresa y una API. Tiene un plan vigente y un rango de fechas. Cada pago confirmado extiende la fecha de fin.

Token

La credencial que usa tu sistema para llamar a la API. Es propio de tu empresa, de esa API y de un entorno. Un token de una API no sirve en otra.

Entorno

Desarrollo (simulado), Pruebas o Producción. Lo define el token, no la URL.

Primeros pasos

1. Crea la cuenta de tu empresa.
2. Elige una API en la lista de APIs y contrata un plan. Los planes gratuitos se activan al instante; los de pago, cuando confirmamos tu pago.
3. En Mis suscripciones > Gestionar crea un token de Desarrollo. Cópialo: solo se muestra una vez.
4. Prueba la conexión:

   curl https://api.inercia.pe/api/v1/estado \
     -H "Authorization: Bearer inr_dev_TU_TOKEN"

5. Sigue la documentación de la API que contrataste. Cuando todo funcione, crea un token de Pruebas y luego uno de Producción.

Autenticación

Envía el token en cada solicitud con la cabecera Authorization:

Authorization: Bearer inr_live_9fK2xQ...

Si tu herramienta no permite esa cabecera, puedes usar X-Api-Key: inr_live_9fK2xQ....

El prefijo indica el entorno: inr_dev_ (Desarrollo), inr_test_ (Pruebas) e inr_live_ (Producción). Guardamos solo una huella SHA-256 del token: si lo pierdes no podemos recuperarlo; revócalo y crea otro.

Un token deja de funcionar si lo revocas, si vence o se suspende la suscripción, o si tu empresa se desactiva.

Entornos

Cada entorno tiene su propia numeración y sus propios registros: un token de pruebas no ve los comprobantes de producción.

Seguridad del token

Además del token, cada uno puede tener protecciones opcionales que configuras en el portal (Gestionar > Tokens > Opciones):

• IPs permitidas: lista de IPs o rangos CIDR (ej. 190.12.34.56, 190.12.34.0/24). Si alguien roba el token, no podrá usarlo desde otra IP. Recomendado en producción.
• Firma HMAC: cada solicitud lleva una firma calculada con un secreto que nunca viaja por la red. Impide usar un token robado sin el secreto y bloquea la repetición de solicitudes capturadas.

Otras protecciones siempre activas: HTTPS obligatorio, límite de solicitudes por minuto, bitácora de cada llamada (visible en el portal) y cifrado de tus credenciales guardadas.

Firma HMAC

Si activaste la firma en un token, agrega estas cabeceras a cada solicitud:

• X-Marca-Tiempo: hora actual en formato Unix (segundos). Se acepta una diferencia máxima de 5 minutos con nuestro servidor.
• X-Firma: HMAC-SHA256 en hexadecimal del texto de abajo, usando tu secreto whsec_... como llave.

Texto a firmar (4 líneas separadas por \n):

{marcaTiempo}
{MÉTODO en mayúsculas}
{ruta y consulta, ej. /api/v1/mensajes/texto}
{SHA-256 en hexadecimal del cuerpo exacto que envías (vacío si no hay cuerpo)}

Cada firma se acepta una sola vez: genera una nueva por solicitud.

C# (.NET)

using System.Security.Cryptography;
using System.Text;

static (string MarcaTiempo, string Firma) Firmar(string secreto, string metodo, string rutaYConsulta, byte[] cuerpo)
{
    var marcaTiempo = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
    var hashCuerpo = Convert.ToHexString(SHA256.HashData(cuerpo)).ToLowerInvariant();
    var mensaje = $"{marcaTiempo}\n{metodo.ToUpperInvariant()}\n{rutaYConsulta}\n{hashCuerpo}";
    var firma = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secreto), Encoding.UTF8.GetBytes(mensaje));
    return (marcaTiempo, Convert.ToHexString(firma).ToLowerInvariant());
}

// Uso: firma el MISMO arreglo de bytes que envías como cuerpo.
var cuerpo = Encoding.UTF8.GetBytes(json);
var (marca, firma) = Firmar(secreto, "POST", "/api/v1/mensajes/texto", cuerpo);
solicitud.Headers.Add("X-Marca-Tiempo", marca);
solicitud.Headers.Add("X-Firma", firma);
solicitud.Content = new ByteArrayContent(cuerpo);
solicitud.Content.Headers.ContentType = new("application/json");

Node.js

const crypto = require("crypto");

function firmar(secreto, metodo, rutaYConsulta, cuerpo) {
  const marcaTiempo = Math.floor(Date.now() / 1000).toString();
  const hashCuerpo = crypto.createHash("sha256").update(cuerpo).digest("hex");
  const mensaje = `${marcaTiempo}\n${metodo.toUpperCase()}\n${rutaYConsulta}\n${hashCuerpo}`;
  const firma = crypto.createHmac("sha256", secreto).update(mensaje).digest("hex");
  return { marcaTiempo, firma };
}

PHP

function firmar(string $secreto, string $metodo, string $rutaYConsulta, string $cuerpo): array {
    $marcaTiempo = (string) time();
    $mensaje = $marcaTiempo . "\n" . strtoupper($metodo) . "\n" . $rutaYConsulta . "\n" . hash('sha256', $cuerpo);
    return [$marcaTiempo, hash_hmac('sha256', $mensaje, $secreto)];
}

Reintentos seguros (idempotencia)

Si se corta la conexión después de enviar una solicitud, no sabrás si se procesó. Para reintentar sin duplicar, envía la cabecera Idempotency-Key con un valor único por operación (8 a 80 letras, números, - o _), por ejemplo el id de tu venta:

Idempotency-Key: venta-000123

Si repites la solicitud con la misma clave, te devolvemos el resultado original (con "repetido": true) en lugar de crear otro registro.

Límites

• Solicitudes por minuto por token, según tu plan. Cada respuesta incluye X-Limite-Minuto y X-Restantes-Minuto. Si lo superas recibirás 429 con la cabecera Retry-After (segundos que debes esperar).
• Consumo mensual (ej. comprobantes por mes), separado para producción y para desarrollo/pruebas. Se reinicia el día 1 de cada mes (hora de Perú). Puedes ver tu consumo en el portal.
• Tamaño máximo de una solicitud: 1 MB.

Errores

Todas las respuestas de error tienen el mismo formato. Usa codigo en tu programa y muestra mensaje a las personas:

{
  "codigo": "validacion",
  "mensaje": "La solicitud tiene errores de validación.",
  "errores": [
    "numero: debe tener el código de país, ej. 51924246085 (Perú: también 924246085).",
    "texto: es obligatorio."
  ]
}

Buenas prácticas

• Guarda los tokens y secretos en variables de entorno o un gestor de secretos, nunca en el código fuente ni en el navegador.
• Usa un token distinto por sistema o sucursal: si uno se compromete, revocas solo ese.
• En producción, activa la restricción por IP y, si puedes, la firma HMAC.
• Envía siempre Idempotency-Key en las operaciones que crean algo.
• Ante 429 o errores de red, reintenta con espera creciente (1 s, 2 s, 4 s...).
• Revisa la vigencia de tu suscripción en el portal: te mostramos un aviso 7 días antes del vencimiento.