Empezá en 5 minutos
Pedí una API key, validala, creá tu primer envío y suscribite a eventos. Sin librerías, sin negociar contratos.
Conseguí tu API key
Pedile a tu administrador que entre al dashboard, sección Integraciones → API Keys, y genere una key con los scopes shipments:write, events:read y webhooks:manage.
La key se ve UNA sola vez al crearla. Guardala en tu gestor de secretos. Formato: mss_live_* para producción o mss_test_* para sandbox.
export MASSIMPLE_BASE=https://api.massimple.la/v1, export MASSIMPLE_KEY=mss_test_xxx.
Validá que la key funciona
El endpoint /v1/whoami te devuelve la aplicación y la compañía a la que apunta tu key. Sanity check antes de cualquier otra cosa.
curl $MASSIMPLE_BASE/whoami \
-H "Authorization: Bearer $MASSIMPLE_KEY"Esperás 200 con:
{
"application": {
"id": "...",
"name": "Mi integración",
"env": "test",
"scopes": ["shipments:write", "events:read", "webhooks:manage"]
},
"company_id": "..."
}Creá tu primer envío
POST a /v1/shipments con el centro de distribución y los datos del destinatario. El header Idempotency-Key es opcional pero recomendado: cualquier retry con la misma key no duplica el envío.
curl -X POST $MASSIMPLE_BASE/shipments \
-H "Authorization: Bearer $MASSIMPLE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"originDistributionCenter": "<ID-DC>",
"destination": {
"destinyName": "Juan Pérez",
"address": "Av. Corrientes 1234, CABA",
"latitude": -34.6037,
"longitude": -58.3816,
"contactName": "Juan Pérez",
"contactPhone": "+5491155557777"
},
"content": "Caja con dos productos",
"amountToCollect": 0,
"scheduledDate": "2026-05-20",
"status": "pending"
}'Respuesta 201 con el envío creado, incluyendo _id y trackingNumber auto-generado.
Suscribite a eventos con un webhook
Registrá una URL HTTPS pública en el dashboard (Integraciones → Webhooks) o por API. Cada vez que algo cambia (estado de envío, de ruta, etc.) te mandamos un POST firmado.
curl -X POST $MASSIMPLE_BASE/webhooks \
-H "Authorization: Bearer $MASSIMPLE_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.tuempresa.com/webhooks/massimple",
"events": ["*"]
}'Te devolvemos un secret que se muestra UNA vez. Guardalo para verificar la firma HMAC de cada delivery.
X-MasSimple-Signature: t=<unix-time>,v1=<hmac-hex>. La firma se computa sobre <timestamp>.<body-raw> usando tu secret. Verificá la firma siempre, sobre el body RAW (no parseado).
Verificá la firma de cada webhook
Snippet de referencia en Node.js. Copialo y pegalo en tu servidor.
import crypto from 'crypto';
export function verifySignatureHeader({ header, body, secret, maxAgeSeconds = 300 }) {
if (typeof header !== 'string') return false;
const parts = Object.fromEntries(
header.split(',').map((p) => {
const idx = p.indexOf('=');
return idx === -1 ? [p, ''] : [p.slice(0, idx).trim(), p.slice(idx + 1)];
}),
);
const ts = Number(parts.t);
if (!Number.isFinite(ts)) return false;
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - ts) > maxAgeSeconds) return false;
const expected = crypto.createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');
const provided = parts.v1 || '';
if (provided.length !== expected.length) return false;
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
}Si el verificador devuelve true, ya podés parsear el body y procesar el evento. Devolvé 200 al final — cualquier 5xx dispara nuestro retry exponencial (1m, 5m, 30m, 2h, 12h, 24h).