ModoFactura API

Idempotency-Key

Tipo string . Patrón: ^[\x21-\x7e]{1,255}$

Lo piden:

• POST /v1/comprobantesPedir un comprobante
• POST /v1/comprobantes/{id}/notas-de-creditoPedir una nota de crédito sobre una factura

Cómo se comporta, según Pedir un comprobante:

Repetir el pedido con el mismo Idempotency-Key y el mismo cuerpo devuelve el mismo comprobante, en su estado actual, y no crea otro. La comparación es por contenido: el orden de los campos o escribir 121 en vez de 121.00 no cambia el pedido. La misma clave con otro cuerpo es un 409. Ante un 500 o un corte, hay que repetir con la misma clave.

Verificar la firma

Un ejemplo en Node.js: es el que menciona la descripción del webhook, y el mismo código que corre la suite de pruebas de ModoFactura.

const { createHmac, timingSafeEqual } = require('node:crypto');

const TOLERANCIA_S = 300;

/**
 * `crudo` son los bytes recibidos. Con Express: `express.raw({ type: 'application/json' })`.
 * `firma` es el encabezado X-ModoFactura-Firma.
 */
function verificarFirma({ secreto, crudo, firma, ahora = Date.now() }) {
  const partes = Object.fromEntries(String(firma).split(',').map((p) => p.split('=', 2)));
  if (!/^\d+$/.test(partes.t ?? '') || !partes.v1) return false;
  if (Math.abs(ahora / 1000 - Number(partes.t)) > TOLERANCIA_S) return false;
  const esperada = createHmac('sha256', secreto).update(`${partes.t}.`).update(crudo).digest();
  const recibida = Buffer.from(partes.v1, 'hex');
  return recibida.length === esperada.length && timingSafeEqual(recibida, esperada);
}

Problema

• No admite campos que no estén en esta tabla.

ProblemaDeValidacion

• No admite campos que no estén en esta tabla.

400

• Falta el Idempotency-Key, es inválido, o el cuerpo no es JSON válido.

  En: POST /v1/comprobantes, POST /v1/comprobantes/{id}/notas-de-credito.

• El cuerpo no es JSON válido.

  En: PUT /v1/webhook.

401

• La clave falta, es inválida, está revocada o es de otro ambiente. La respuesta no distingue cuál.

  Encabezados: WWW-Authenticate.

  En todas las operaciones.

404

• No hay un comprobante de este cliente con ese id. La respuesta no distingue si existe para otro.

  En: GET /v1/comprobantes/{id}, POST /v1/comprobantes/{id}/notas-de-credito, GET /v1/comprobantes/{id}/pdf, POST /v1/comprobantes/{id}/webhook/reenviar.

• La cuenta no tiene un webhook registrado.

  En: GET /v1/webhook, DELETE /v1/webhook, POST /v1/webhook/secreto.

409

• El Idempotency-Key ya se usó con otro cuerpo, o a la cuenta le falta el punto de venta o sus datos fiscales de emisor. title dice cuál. No se encoló nada.

  En: POST /v1/comprobantes.

• El comprobante no es una factura o todavía no está emitido; se emitió con un CUIT distinto del que tiene hoy la cuenta; la nota superaría a la factura sumada a las otras; el Idempotency-Key ya se usó con otro cuerpo; o a la cuenta le falta el punto de venta o sus datos fiscales. title dice cuál. No se encoló nada.

  En: POST /v1/comprobantes/{id}/notas-de-credito.

• No hay PDF para servir. title dice por qué: el comprobante no está emitido (todavía, o fue rechazado); se creó sin los datos del emisor; o el archivo generado no coincide con el original, caso en el que no se sirve y lo revisa una persona. Reintentar sólo sirve en el primer caso, cuando el comprobante esté emitido.

  En: GET /v1/comprobantes/{id}/pdf.

• No hay nada que enviar. title dice por qué: la cuenta no tiene webhook registrado, o el comprobante todavía no tiene un resultado.

  En: POST /v1/comprobantes/{id}/webhook/reenviar.

413

• El cuerpo supera los 256 KB.

  En: POST /v1/comprobantes, POST /v1/comprobantes/{id}/notas-de-credito, PUT /v1/webhook.

415

• El cuerpo no es application/json, o viene comprimido.

  En: POST /v1/comprobantes, POST /v1/comprobantes/{id}/notas-de-credito, PUT /v1/webhook.

422

• El pedido está bien formado pero no se puede emitir. errores dice por qué. No se encoló nada.

  En: POST /v1/comprobantes, POST /v1/comprobantes/{id}/notas-de-credito.

• La URL no se admite. Un destino que no resuelve y uno interno dan el mismo error.

  En: PUT /v1/webhook.

429

• Se superó el límite de pedidos del cliente, su tope de pedidos sin procesar, el de autenticaciones fallidas de la IP, o hay demasiados PDF generándose a la vez. Por defecto, 300 pedidos por minuto por cliente, 1000 sin procesar por cliente y 20 autenticaciones fallidas por minuto por IP. Reintentar con el mismo Idempotency-Key es seguro.

  Encabezados: Retry-After (Segundos hasta poder volver a intentar.).

  En todas las operaciones.

500

• Error interno, sin detalles. Se puede reintentar; en un POST, con el mismo Idempotency-Key.

  En todas las operaciones.

503

• La entrega de webhooks no está encendida en este ambiente. No se registró ni se encoló nada.

  En: POST /v1/comprobantes/{id}/webhook/reenviar, PUT /v1/webhook, POST /v1/webhook/secreto.