{
  "format": "arista-api-schema",
  "schema_version": "1.0",
  "api": {
    "name": "Arista Delivery API",
    "version": "v1",
    "protocol": "HTTPS",
    "media_type": "application/json"
  },
  "environments": [
    {
      "name": "TEST",
      "base_url": "https://sandbox-api.example.com/v1",
      "credential_prefix": "ari_test_",
      "effects": "simulated"
    },
    {
      "name": "LIVE",
      "base_url": "https://api.example.com/v1",
      "credential_prefix": "ari_live_",
      "effects": "production"
    }
  ],
  "authentication": {
    "type": "bearer",
    "header": "Authorization",
    "example": "Bearer ari_test_..."
  },
  "request_headers": {
    "Content-Type": "application/json",
    "Idempotency-Key": "Required for creation and cancellation operations",
    "X-Arista-Key": "Alternative API-key header"
  },
  "request_id": {
    "response_header": "X-Arista-Request-Id",
    "body_field": "request_id"
  },
  "scopes": [
    "shipments:quote",
    "shipments:create",
    "shipments:read",
    "shipments:cancel",
    "tracking:read",
    "webhooks:manage"
  ],
  "endpoints": [
    {
      "method": "GET",
      "path": "/health",
      "auth": false,
      "description": "Service health"
    },
    {
      "method": "GET",
      "path": "/schema.json",
      "auth": false,
      "description": "Public machine-readable API contract"
    },
    {
      "method": "POST",
      "path": "/shipments/quote",
      "auth": true,
      "scope": "shipments:quote",
      "description": "Quote a shipment"
    },
    {
      "method": "GET",
      "path": "/shipments",
      "auth": true,
      "scope": "shipments:read",
      "description": "List shipments"
    },
    {
      "method": "POST",
      "path": "/shipments",
      "auth": true,
      "scope": "shipments:create",
      "idempotency": true,
      "description": "Create a shipment"
    },
    {
      "method": "GET",
      "path": "/shipments/{shipment_number}",
      "auth": true,
      "scope": "shipments:read",
      "description": "Get a shipment"
    },
    {
      "method": "POST",
      "path": "/shipments/{shipment_number}/cancel",
      "auth": true,
      "scope": "shipments:cancel",
      "idempotency": true,
      "description": "Cancel a shipment"
    },
    {
      "method": "GET",
      "path": "/tracking/{shipment_number}",
      "auth": true,
      "scope": "tracking:read",
      "description": "Get tracking events"
    },
    {
      "method": "POST",
      "path": "/sandbox/shipments/{shipment_number}",
      "environment": "TEST",
      "auth": true,
      "scope": "shipments:create",
      "description": "Simulate a shipment status"
    }
  ],
  "shipment_request": {
    "recipient": {
      "name": "Cliente Demo",
      "phone": "55555555",
      "address": "6a avenida 4-20",
      "zone": "10",
      "municipality": "Guatemala",
      "reference": "Portón gris"
    },
    "pickup": {
      "address": "San Marcos",
      "municipality": "San Marcos"
    },
    "package": {
      "content": "Ropa",
      "pieces": 1,
      "weight_lbs": "2.00"
    },
    "cod": {
      "amount": "0.00"
    },
    "instructions": "Llamar antes de entregar",
    "reference": "ORD-10025"
  },
  "sandbox_statuses": [
    "created",
    "picked_up",
    "in_transit",
    "out_for_delivery",
    "delivered",
    "returned",
    "cancelled"
  ],
  "webhooks": {
    "transport": "HTTPS POST JSON",
    "signature": "HMAC-SHA256",
    "signature_header": "X-Arista-Signature",
    "timestamp_header": "X-Arista-Timestamp",
    "event_id_header": "X-Arista-Event-Id",
    "events": [
      "shipment.created",
      "shipment.picked_up",
      "shipment.in_transit",
      "shipment.out_for_delivery",
      "shipment.delivered",
      "shipment.cancelled",
      "shipment.returned"
    ]
  },
  "errors": {
    "shape": {
      "error": {
        "code": "string",
        "message": "string"
      },
      "request_id": "req_..."
    },
    "status_codes": {
      "400": "Invalid request",
      "401": "Authentication failed",
      "403": "Permission denied",
      "404": "Not found",
      "409": "Operational or idempotency conflict",
      "422": "Validation error",
      "429": "Rate limit exceeded",
      "500": "Internal error",
      "503": "Service unavailable"
    }
  }
}