La API de trámites de Managora

Necesita una clave. Se emiten dos, en momentos distintos: primero la de pruebas (mgk_sandbox_…) y, cuando haya recorrido el flujo entero, la de producción (mgk_live_…). Escríbanos a tramites@managora.net.

curl https://managora.net/api/partner/v1/me \
  -H "Authorization: Bearer $MANAGORA_API_KEY"

curl https://managora.net/api/partner/v1/services \
  -H "Authorization: Bearer $MANAGORA_API_KEY"

curl https://managora.net/api/partner/v1/services/titulo_nautico_per \
  -H "Authorization: Bearer $MANAGORA_API_KEY"

curl -X POST https://managora.net/api/partner/v1/orders \
  -H "Authorization: Bearer $MANAGORA_API_KEY" \
  -H "Idempotency-Key: pedido-4417" \
  -H "Content-Type: application/json" \
  -d '{
    "tramite": "titulo_nautico_per",
    "referencia": "4417",
    "datos": { "...": "GET /services/titulo_nautico_per" }
  }'

A partir de ahí, el enlace sale por correo a su cliente y usted sigue el pedido con GET /orders/{id} o esperando los webhooks.

Una clave mgk_sandbox_ recorre el mismo código que una real: mismas comprobaciones, mismo expediente, misma pantalla y mismo escrito. Lo único que cambia es que no hay cobro.

En la pantalla de su cliente, donde iría el botón de pago, sale uno que dice Simular el pago y continuar, con el aviso de que es una prueba. A partir de ahí el trámite sigue igual: se genera el escrito y salen los webhooks.

1. Usted crea el pedido con los datos de su cliente. Comprobamos que el trámite procede, que los valores son de los admitidos y que el generador del escrito puede redactar con ellos. Si algo falla, se rechaza antes de crear nada.
2. Nosotros le mandamos el enlace a su cliente, por correo. Es personal, de un solo uso y caduca (de 24 a 168 horas, a su elección).
3. Su cliente revisa, firma y paga en managora.net, con su navegador.
4. Un profesional de Managora prepara y presenta el expediente y escribe la referencia real que devuelve el organismo.

Cinco eventos, y solo cinco. Cada uno se emite desde el sitio que escribe ese hecho.

Se registran desde la propia API (POST /webhooks) y se pueden editar, rotar el secreto, apagar y volver a encender sin escribirnos.

La firma

Cada aviso lleva Managora-Signature: t=<epoch>,v1=<hex>. El valor es un HMAC-SHA256 de <t>.<cuerpo crudo> con el secreto del endpoint.

• Hexadecimal en minúsculas.
• El secreto se usa como bytes UTF-8, con el prefijo whsec_ incluido y sin decodificar.
• Firme el cuerpo crudo que recibe, nunca el JSON reserializado: es el fallo número uno al validar un HMAC.
• Rechace lo que llegue con más de 5 minutos de antigüedad.
• Durante una rotación van dos v1 y le basta con validar una.

const crypto = require("crypto");

function firmaValida(cuerpoCrudo, cabecera, secreto) {
  const partes = String(cabecera).split(",").map((p) => p.trim());
  const t = Number(partes.find((p) => p.startsWith("t="))?.slice(2));
  if (!Number.isFinite(t)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > 300) return false;

  const esperada = crypto
    .createHmac("sha256", secreto)
    .update(`${t}.${cuerpoCrudo}`)
    .digest("hex");

  return partes
    .filter((p) => p.startsWith("v1="))
    .some((p) => {
      const a = Buffer.from(esperada, "utf8");
      const b = Buffer.from(p.slice(3), "utf8");
      return a.length === b.length && crypto.timingSafeEqual(a, b);
    });
}

<?php
function firma_valida(string $cuerpoCrudo, string $cabecera, string $secreto): bool {
    $partes = array_map('trim', explode(',', $cabecera));
    $t = null;
    foreach ($partes as $p) {
        if (str_starts_with($p, 't=')) { $t = (int) substr($p, 2); }
    }
    if ($t === null || abs(time() - $t) > 300) { return false; }

    $esperada = hash_hmac('sha256', $t . '.' . $cuerpoCrudo, $secreto);

    foreach ($partes as $p) {
        if (str_starts_with($p, 'v1=') && hash_equals($esperada, substr($p, 3))) {
            return true;
        }
    }
    return false;
}

Entrega

Conteste 2xx en cuanto reciba y procese después. Cortamos a los 10 segundos y no seguimos redirecciones: un 3xx lo contamos como fallo. Reintentamos a 1 minuto, 5, 30, 2 horas y 6 horas. La entrega es at-least-once: deduplique por la cabecera Managora-Entrega-Id header, que es la misma en todos los reintentos del mismo aviso.

Si su endpoint falla 20 veces seguidas lo apagamos y se lo decimos por correo. Lo vuelve a encender con POST /webhooks/{id}/reactivate, que además reencola lo que no llegó. Y GET /events es el historial completo, con el cuerpo de cada aviso.

Todos los errores tienen la misma forma. Ramifique por error.codigo, que es estable; el mensaje está escrito para que lo lea una persona y puede cambiar.

{
  "error": {
    "codigo": "datos_invalidos",
    "mensaje": "Hay campos con valores que no admitimos.",
    "campo": "datos",
    "detalles": [
      {
        "campo": "lista",
        "etiqueta": "Lista del registro",
        "motivo": "\"Lista 7\" no es uno de los valores admitidos.",
        "opciones": ["Lista 3 (pesca)", "Lista 6 (alquiler)", "Lista 7 (recreo)"]
      }
    ]
  }
}

Los más habituales. La tabla completa, con los 52, está en la referencia.

• 120 peticiones por minuto y clave. Cada respuesta trae X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset, para que frene antes de chocar.
• Idempotency-Key obligatoria en cada pedido. Un reintento con el mismo cuerpo devuelve el mismo pedido con reintento: true. Con un cuerpo distinto devuelve 409: eso no es un reintento, y darle por bueno el pedido viejo le haría creer que se guardó lo nuevo.
• La referencia es única por cuenta y no se reutiliza, ni siquiera para el mismo cliente.
• Los ficheros no van en la API. Los sube su cliente desde su pantalla, después de pagar, y usted ve lo que falta en documentos_pendientes.
• Todo es JSON, también los errores. Una ruta mal escrita o un método equivocado devuelven el mismo sobre, nunca una página HTML.