Autenticación

La API utiliza tokens opacos (API keys). Hay dos clases:

Personal: la gestiona cada usuario en el panel de API keys y actúa en su nombre.
De aplicación: pertenece a una aplicación consumidora (service account) y actúa como esa aplicación, con un usuario responsable detrás.

Cómo enviar la API key

Incluye el token en cada petición con el encabezado:

Authorization: Bearer <token>

Scopes

Cada key declara los scopes con los que se creó (por ejemplo catalogos:read o cfdi:generar), y no se pueden ampliar después: para dar más alcance se crea otra key. El alcance efectivo de una petición es la intersección de los scopes del token y el permiso del sujeto; falta cualquiera de los dos y la respuesta es 403. La lista completa y la matriz por endpoint están en Integración entre aplicaciones.

Formato de los errores

Toda la API responde el mismo envelope, con un codigo estable que es lo que debe leer tu aplicación:

{
  "error": {
    "codigo": "scope_insuficiente",
    "mensaje": "El token no tiene los scopes requeridos",
    "detalles": ["cfdi:generar"]
  }
}

Errores comunes

Código HTTP	Significado
401	Falta el encabezado `Authorization`, el token no existe, fue revocado o expiró, o la cuenta responsable está suspendida.
403	El token es válido pero le falta un scope (`scope_insuficiente`) o al sujeto le falta el permiso (`permiso_insuficiente`), o su rol de acceso al emisor no permite la operación (`acceso_denegado`).
404	El recurso no existe o el token no tiene acceso a él: no se revela la diferencia.
409	Conflicto: ya existe un sello para ese RFC o una aplicación con ese slug.
422	La petición se entiende pero los datos no pasan la validación (CFDI inválido, CSD rechazado).
502	Falló un sistema externo: el proveedor de timbrado o el WS del SAT.

El catálogo completo de códigos está en /docs/integracion y en la especificación OpenAPI.