GreenStack API v2 — Especificación Técnica

Versión 2.1.0 · Actualizado 2026-06-12 · Acceso solo para integradores certificados.

Esta especificación describe todos los endpoints REST de la plataforma GreenStack para la gestión de huella de carbono empresarial. La API sigue los principios REST; los recursos devuelven JSON y las respuestas de error siguen RFC 9457.

Autenticación

OAuth 2.0 — Client Credentials

La API usa el flujo Client Credentials de OAuth 2.0. Obtén un token de acceso con:

CopyPOST https://auth.greenstack.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=emissions:read emissions:write reports:read

Respuesta:

Copy{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "emissions:read emissions:write reports:read"
}

Incluye el token en cada petición:

CopyAuthorization: Bearer {access_token}

Scopes disponibles

Recursos

Organizaciones

Una organización representa a la empresa cliente. Todas las peticiones van namespaced por org_id.

GET /v2/orgs/{org_id}

Devuelve los metadatos de una organización.

CopyGET /v2/orgs/org_01HXYZ1234 HTTP/1.1
Host: api.greenstack.io
Authorization: Bearer {token}

Respuesta 200 OK:

Copy{
  "id": "org_01HXYZ1234",
  "name": "Café Raíz SL",
  "country": "ES",
  "sector": "food_beverage",
  "reporting_year": 2025,
  "baseline_year": 2022,
  "created_at": "2024-03-15T09:22:00Z",
  "status": "active"
}

PATCH /v2/orgs/{org_id}

Actualiza campos de la organización. Solo name, country y reporting_year son mutables.

Copy{
  "reporting_year": 2025
}

Emisiones

Los registros de emisiones representan actividades con impacto de carbono. Cada registro pertenece a un scope (1, 2 o 3) y a una categoría GHG Protocol.

Modelo de datos

GET /v2/orgs/{org_id}/emissions

Lista registros con paginación tipo cursor.

Parámetros de query:

Respuesta 200 OK:

Copy{
  "data": [
    {
      "id": "01HXAB1234",
      "scope": 1,
      "category": "stationary_combustion",
      "activity_value": 1200.5,
      "activity_unit": "kWh",
      "co2e_kg": 264.11,
      "date": "2025-10-01",
      "tags": ["planta-madrid", "produccion"]
    }
  ],
  "cursor_next": "eyJpZCI6IjAxSFhBQjEyMzQifQ",
  "total_count": 847,
  "has_more": true
}

POST /v2/orgs/{org_id}/emissions

Crea un nuevo registro.

Copy{
  "scope": 2,
  "category": "purchased_electricity",
  "activity_value": 8540.0,
  "activity_unit": "kWh",
  "emission_factor_id": "ef_es_grid_2025",
  "date": "2025-11-30",
  "notes": "Factura nov 2025, contrato Endesa verde",
  "tags": ["oficina-bcn"]
}

Respuesta 201 Created:

Copy{
  "id": "01HXBC5678",
  "co2e_kg": 1282.6,
  "co2e_kg_details": {
    "factor_value": 0.15,
    "factor_unit": "kgCO2e/kWh",
    "factor_version": "MiTECO-2025"
  }
}

DELETE /v2/orgs/{org_id}/emissions/{emission_id}

Elimina un registro. Operación irreversible. Requiere scope emissions:write.

Respuesta: 204 No Content.

Factores de emisión

Base de datos de referencia con más de 12.000 factores certificados (DEFRA, MiTECO, IPCC AR6).

GET /v2/emission-factors

CopyGET /v2/emission-factors?country=ES&category=purchased_electricity&year=2025

Respuesta 200 OK:

Copy{
  "data": [
    {
      "id": "ef_es_grid_2025",
      "name": "Red eléctrica española 2025",
      "country": "ES",
      "category": "purchased_electricity",
      "value": 0.15,
      "unit": "kgCO2e/kWh",
      "source": "MiTECO",
      "year": 2025,
      "status": "active"
    }
  ]
}

Informes

Los informes se generan de forma asíncrona. El flujo es: lanzar → polling de estado → descargar.

POST /v2/orgs/{org_id}/reports

Lanza la generación de un informe.

Copy{
  "type": "annual_ghg",
  "year": 2025,
  "format": "pdf",
  "standard": "GHG_Protocol",
  "locale": "es"
}

Tipos de informe disponibles:

• annual_ghg — Inventario anual completo GHG Protocol
• scope3_deep — Desglose detallado alcance 3 (15 categorías)
• carbon_footprint_product — Huella de producto (PCF ISO 14067)
• executive_summary — Resumen ejecutivo de 4 páginas

Respuesta 202 Accepted:

Copy{
  "report_id": "rpt_01HXDE1234",
  "status": "queued",
  "estimated_seconds": 45
}

GET /v2/orgs/{org_id}/reports/{report_id}

Polling de estado.

GET /v2/orgs/{org_id}/reports/{report_id}/download

Descarga el archivo. Redirige (302) al URL firmado de S3 (válido 15 minutos).

Manejo de errores

La API sigue RFC 9457 (Problem Details for HTTP APIs):

Copy{
  "type": "https://errors.greenstack.io/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "activity_value must be a positive number",
  "instance": "/v2/orgs/org_01HXYZ1234/emissions",
  "errors": [
    { "field": "activity_value", "code": "must_be_positive", "value": -10 }
  ]
}

Códigos de estado habituales

Rate Limiting

Los límites se aplican por client_id:

Las cabeceras X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset están presentes en cada respuesta.

Webhooks

Suscríbete a eventos asíncronos para evitar polling activo.

Eventos disponibles

• emission.created — nuevo registro creado
• emission.updated — registro modificado
• report.ready — informe listo para descarga
• report.failed — error en generación
• org.limit_warning — acercándose al límite de emisiones del plan

Firma de seguridad

Cada entrega incluye la cabecera X-GreenStack-Signature:

Copyimport hmac, hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

SDKs y ejemplos

Librerías oficiales mantenidas por el equipo GreenStack:

Ejemplo completo Python

Copyfrom greenstack import GreenStackClient

client = GreenStackClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
)

# Crear registro de emisiones
record = client.emissions.create(
    org_id="org_01HXYZ1234",
    scope=2,
    category="purchased_electricity",
    activity_value=8540.0,
    activity_unit="kWh",
    emission_factor_id="ef_es_grid_2025",
    date="2025-11-30",
)
print(f"Registro {record.id}: {record.co2e_kg:.2f} kgCO2e")

# Generar informe anual
report = client.reports.generate(
    org_id="org_01HXYZ1234",
    type="annual_ghg",
    year=2025,
    format="pdf",
)
report.wait()  # bloquea hasta status=ready
report.download(path="./informe_ghg_2025.pdf")
print("Informe descargado.")

Changelog

v2.1.0 (2026-06-12)

• Nuevo tipo de informe carbon_footprint_product (PCF ISO 14067)
• Endpoint GET /v2/emission-factors ahora acepta year como parámetro
• Tiempo de expiración de informes extendido de 7 a 30 días
• SDK Python actualizado a 2.1.0 con soporte async/await

v2.0.0 (2025-09-01)

• Migración a OAuth 2.0 (abandono de API Keys v1)
• Modelo de datos de emisiones rediseñado (campo co2e_kg calculado en servidor)
• Nuevos scopes granulares: reports:generate, admin:orgs
• Webhooks con firma HMAC-SHA256

v1.9 (deprecada)

• Última versión con API Keys. Soporte hasta 2026-09-01.

Documentación generada por CULTIVA IA para GreenStack SaaS. Para soporte de integración: developers@greenstack.io