Integración entre aplicaciones

Cómo se identifica una aplicación que consume esta API, qué puede hacer, cómo se configura sin intervención humana y cómo se reporta un error. Toda la gestión está disponible por REST y por MCP con las mismas reglas.

Identidad: usuario o aplicación

Toda petición lleva un token Bearer que se resuelve a un principal. Hay dos tipos, y se distinguen en la autorización y en la auditoría:

Toda aplicación tiene un usuario responsable: si su cuenta se suspende, o si la aplicación se desactiva en /aplicaciones, sus keys dejan de autenticar de inmediato (401).

Autorización en dos capas

El alcance efectivo de una petición es la intersección del permiso del sujeto y de los scopes del token. Falta cualquiera de los dos y la respuesta es 403.

1. Permiso del sujeto (Casbin): lo da el rol —admin, usuario (todo humano con cuenta) o aplicacion—.
2. Scopes del token: se eligen al crear la API key y no se pueden ampliar después; para dar más alcance se crea otra key.

El acceso a los emisores tampoco lo da ninguna de las dos capas: lo da la cuenta maestra (tenant) del principal, y cada consulta filtra por cuenta_id. Un RFC es único dentro de su cuenta y puede repetirse en otras, donde es un sello independiente e invisible. Un identificador enviado por el cliente nunca autoriza por sí solo. Las cuentas maestras se gestionan en /cuentas.

Scopes disponibles

Endpoints de gestión

Bootstrap de una integración

Con una key de administrador (scopes aplicaciones:write, apikeys:manage y empresas:write), el alta de una aplicación consumidora no requiere tocar el panel:

# 1. Registrar la aplicación
curl -sX POST $BASE/api/v1/aplicaciones \
  -H "Authorization: Bearer $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"nombre":"AD CFDI","slug":"ad-cfdi"}'

# 2. Crear su API key con los scopes mínimos (el token se muestra una sola vez)
curl -sX POST $BASE/api/v1/aplicaciones/ad-cfdi/keys \
  -H "Authorization: Bearer $ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"nombre":"prod","scopes":["cfdi:generar","empresas:read"],"expira_en":"2027-01-01T00:00:00Z"}'

# 3. Dar de alta el emisor con el CSD en base64
curl -sX POST $BASE/api/v1/empresas \
  -H "Authorization: Bearer $APP_KEY" -H 'Content-Type: application/json' \
  -d "{\"cer_b64\":\"$(base64 -i sello.cer)\",\"key_b64\":\"$(base64 -i sello.key)\",
       \"password\":\"$PASS_CSD\",\"regimen_fiscal\":\"601\"}"

# 4. Generar (y timbrar) con esa key
curl -sX POST "$BASE/api/v1/cfdi/generar/ingreso?timbrar=true" \
  -H "Authorization: Bearer $APP_KEY" -H 'Content-Type: application/json' -d @factura.json

Si el emisor ya existe y lo administra otro principal, el paso 3 es una concesión desde quien administra: POST /api/v1/empresas/<RFC>/accesos con {"aplicacion_slug":"ad-cfdi","rol":"emitir"}.

Reglas que conviene conocer

• Un sello por RFC y cuenta. Si el RFC ya está registrado en la cuenta, el alta responde 409 rfc_duplicado; en otra cuenta se acepta porque es un sello independiente. Rotar un CSD es editar el sello existente.
• Anti-escalada. Con una key solo se crean keys con scopes que esa key ya tiene, y una aplicación solo crea keys de sí misma (403 escalada_de_scopes).
• El token se muestra una sola vez. Ni la API ni el panel permiten volver a consultarlo; si se pierde, se crea otra key y se revoca la anterior.
• 404 opaco. Un emisor que existe pero al que el token no tiene acceso responde 404 empresa_no_encontrada, igual que si no existiera.
• Auditoría y meterización. Cada timbrado guarda en timbrado_operacion la cuenta, el actor (uid:<id> o app:<cuenta>:<slug>) y la aplicación, y el agente recibe ese actor como usuario_plataforma. El consumo por cuenta se acumula en cuenta_uso y se consulta en GET /api/v1/cuenta/uso.
• Licencia. Una cuenta suspendida responde 403 cuenta_suspendida y una sin licencia vigente 402 licencia_vencida; la vigencia la decide el sistema de licenciamiento.

Contrato de errores

Toda la API (/api/v1/* y /mcp) responde el mismo envelope:

{
  "error": {
    "codigo": "empresa_no_encontrada",
    "mensaje": "No tiene acceso a una empresa con ese RFC.",
    "detalles": []
  }
}

codigo es estable y es lo que debe leer un consumidor; mensaje está listo para mostrarse y detalles lleva los scopes faltantes, los campos rechazados o el código del proveedor. La especificación de máquina está en /docs/openapi.yaml.

Migrar una integración existente

Las API keys creadas antes de este modelo siguen funcionando: conservan su usuario como sujeto y recibieron por migración los scopes que ya ejercían (catalogos:read, cfdi:validar, cfdi:generar, cfdi:consulta y actualizaciones:read). Para pasarla al modelo nuevo:

1. Registre la aplicación y cree su key con los scopes mínimos.
2. Conceda a la aplicación el acceso emitir (o administrar) de los RFC que ya usaba.
3. Cambie el token en el consumidor y verifique con GET /api/v1/empresas.
4. Revoque la key personal anterior.

El único cambio obligatorio e inmediato para los consumidores es la forma del envelope de error: antes {"error":"texto"} (y {"codigo","mensaje"} en los fallos del proveedor de timbrado), ahora {"error":{"codigo","mensaje","detalles"}}.