Idempotencia y límites

Idempotency-Key#

En todo POST que crea recursos, manda un header Idempotency-Key con un UUID nuevo por operación. Si repites la solicitud con la misma key, Firmo no crea otro recurso: devuelve el resultado de la primera vez. Las keys se guardan 24 horas.

Idempotency-Key: 7b2f4c1e-9a0d-4f3b-8c55-1d2e3f4a5b6c

• Genera la key cuando creas la factura en tu sistema y guárdala junto a ella. Si el envío falla, reintenta con la misma.
• Si usas la misma key con un cuerpo distinto, la API responde 409 con código idempotencia.
• Además, idExterno es único por empresa: es otra protección contra duplicados.

Límites de uso#

Cada API key puede hacer hasta 600 solicitudes por minuto. Si te pasas, la API responde 429 con código limite_excedido y el header Retry-After con los segundos que debes esperar.

async function conReintento(hacerSolicitud, intentos = 5) {
  for (let i = 0; i < intentos; i++) {
    const res = await hacerSolicitud();
    if (res.status !== 429 && res.status < 500) return res;
    const espera = Number(res.headers.get('Retry-After')) || 2 ** i;
    await new Promise((r) => setTimeout(r, espera * 1000));
  }
  throw new Error('Firmo no respondió después de varios intentos');
}

Paginación#

Los listados devuelven { datos, siguiente }. Pasa el valor de siguiente en el parámetro cursor para pedir la página siguiente, hasta que sea null. Ver Consultar y descargar.