The Managora services API

You need a key. We issue two, at different moments: first the test (mgk_sandbox_…) one and, once you have been through the whole flow, the production (mgk_live_…). Write to us at 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" }
  }'

From there the link goes out by email to your client and you follow the order with GET /orders/{id} or by waiting for the webhooks.

A mgk_sandbox_ key runs through the same code as a real one: same checks, same case file, same screen and same generated document. The only difference is that nothing is charged.

On your client's screen, where the payment button would be, there is one that reads Simulate the payment and continue, with a notice that it is a test. From there the application carries on the same: the document is generated and the webhooks go out.

1. You create the order with your client's data. We check that the service applies, that the values are among the accepted ones and that the document generator can draft with them. If anything fails, it is rejected before anything is created.
2. We send the link to your client, by email. It is personal, single-use and expires (24 to 168 hours, your choice).
3. Your client reviews, signs and pays on managora.net, in their own browser.
4. A Managora professional prepares and files the case file and records the real reference the authority returns.

Five events, and only five. Each one is emitted from the place that writes that fact.

You register them from the API itself (POST /webhooks) and you can edit them, rotate the secret, switch them off and switch them back on without writing to us.

The signature

Every webhook carries Managora-Signature: t=<epoch>,v1=<hex>. The value is an HMAC-SHA256 of <t>.<raw body> with the endpoint secret.

• Lowercase hexadecimal.
• The secret is used as UTF-8 bytes, including the whsec_ prefix and without decoding it.
• Sign the raw body you receive, never the re-serialised JSON: it is the number one mistake when validating an HMAC.
• Reject anything that arrives more than 5 minutes old.
• During a rotation two v1 values are sent and validating one is enough.

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;
}

Delivery

Answer 2xx as soon as you receive and process afterwards. We time out at 10 seconds and do not follow redirects: a 3xx counts as a failure. We retry at 1 minute, 5, 30, 2 hours and 6 hours. Delivery is at-least-once: deduplicate on the Managora-Entrega-Id header, which is the same across every retry of the same webhook.

If your endpoint fails 20 times in a row we switch it off and tell you by email. You switch it back on with POST /webhooks/{id}/reactivate, which also requeues whatever did not arrive. And GET /events is the full history, with the body of every webhook.

Every error has the same shape. Branch on error.codigo, which is stable; the message is written for a human to read and may change.

{
  "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)"]
      }
    ]
  }
}

The most common ones. The full table, with all 52, is in the reference.

• 120 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so you can slow down before you hit the wall.
• Idempotency-Key is required on every order. A retry with the same body returns the same order with reintento: true. With a different body it returns 409: that is not a retry, and handing you back the old order would make you believe the new data was saved.
• The reference is unique per account and is never reused, not even for the same client.
• Files do not travel through the API. Your client uploads them from their own screen, after paying, and you see what is missing in documentos_pendientes.
• Everything is JSON, errors included. A mistyped route or a wrong method returns the same envelope, never an HTML page.