Guías rápidas

Tres formas de conectar

Empieza siempre con una clave c5_test_ (sandbox) y pasa a c5_live_ cuando funcione.

Añade siempre ?forceFunctionRegion= con la región UE del proyecto (la tienes en la referencia) para que tus peticiones se procesen en la UE.

1. Conecta tu programa de facturación (te manda los pedidos)

  1. Crea una clave test con los alcances pedidos:escribir y contactos:escribir.
  2. Da de alta el cliente con POST /v1/contactos (o mándalo dentro del pedido).
  3. Pide la factura con POST /v1/pedidos: responde 202 con estado: pendiente_confirmacion.
  4. Escucha factura.emitida en tu webhook. En el sandbox, simula al titular con POST /v1/sandbox/pedidos/{id}/simular (confirmar, rechazar o cambiar).
  5. Pasa a una clave live: el titular recibirá el resumen por WhatsApp y solo se emite si lo confirma.

2. Recibe tus facturas y gastos en tu ERP

  1. Clave con facturas:leer y gastos:leer.
  2. Webhook a factura.emitida y gasto.registrado. Verifica la firma (abajo).
  3. Al recibir el evento, pide GET /v1/facturas/{id} y su PDF (/pdf, URL de 5 minutos).
  4. Para la primera sincronización, recorre GET /v1/facturas con cursor hasta que siguiente sea null.

Verificar la firma (Node.js)

import crypto from 'node:crypto';

// El cuerpo CRUDO (tal cual llega, sin parsear) y la cabecera ConfIA5-Firma: "t=1760536800,v1=<hex>[,v1=<hex>]".
export function firmaValida(cabecera, cuerpoCrudo, secreto, toleranciaS = 300) {
  const partes = cabecera.split(',').map((p) => p.trim().split('='));
  const t = Number(partes.find(([k]) => k === 't')?.[1]);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranciaS) return false;
  const esperada = crypto.createHmac('sha256', secreto).update(`${t}.${cuerpoCrudo}`).digest('hex');
  // Durante la rotación del secreto llegan dos firmas v1: vale cualquiera. Comparación en tiempo constante.
  return partes
    .filter(([k]) => k === 'v1')
    .some(([, v]) => v && v.length === esperada.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(esperada)));
}

Los eventos llevan ConfIA5-Evento-Id para deduplicar. Reintentamos durante 24 h (1 min, 5 min, 30 min, 2 h, 6 h, 12 h); después el destino se desactiva y te avisamos. No seguimos redirecciones y solo enviamos a https con dominio público.

3. Exporta a tu contabilidad

  1. Clave con exportaciones:crear.
  2. POST /v1/exportaciones con formato: "universal" y el periodo: ZIP con los PDF y los libros en CSV.
  3. Escucha exportacion.lista o consulta GET /v1/exportaciones/{id} para la URL de descarga.
  4. Los formatos de programa (a3, ContaPlus…) llegarán cuando los validemos con ficheros reales: nunca inventamos un formato.