> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhdar-sa.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use {baseUrl} for the environment-specific base URL provided to the partner integration team. Do not invent an API hostname.
> x-akhdar-* fields are publication provenance only. Do not treat them as partner integration instructions.

# Examples

> Copyable cookbook for confirmation, recovery, estimates, and webhook verification. All examples use {baseUrl}.

All examples use `{baseUrl}` rather than a live hostname. Full response fields are in the guides and [API Reference](/api-reference).

## 1. Confirm a contribution

Confirm only after your system has deducted the customer's points.

```bash theme={null}
curl -X POST "{baseUrl}/v1/impact-transactions" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_01HZX5Z9Y8X7W6V5U4T3S2R1" \
  -H "Content-Type: application/json" \
  -d '{"partner_event_id":"evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9","partner_order_ref":"ord_9f3c2a71","points":500,"opaque_customer_ref":"cust_ref_8a1b2c3d"}'
```

A successful confirmation returns HTTP `201` with `status: confirmed`. See [Contributions](/contributions).

## 2. Recover after a timeout

Look up the contribution by `partner_event_id`:

```bash theme={null}
curl -X GET "{baseUrl}/v1/impact-transactions?partner_event_id=evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9" \
  -H "X-API-Key: $AKHDAR_API_KEY"
```

If no contribution is found, the response is not a final failure and does not authorize point restoration. Safe retry of the original confirmation request is permitted:

```json theme={null}
{
  "error": {
    "code": "contribution_not_found",
    "message": "No contribution was found for partner_event_id. This is not a final failure and does not authorize point restoration. Safe retry of the original confirmation request is permitted.",
    "retryable": true,
    "correlation_id": "corr_7c2e9b1a4d6f8e0c"
  }
}
```

See [Errors & Recovery](/errors-and-recovery).

## 3. Estimate, then associate

Create an estimate:

```bash theme={null}
curl -X POST "{baseUrl}/v1/emissions/estimates" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_est_01HZX4K9M2Q8R7N6P5T4V3" \
  -H "Content-Type: application/json" \
  -d '{"partner_order_ref":"ord_9f3c2a71","distance_km":"7.400","distance_unit":"km","vehicle_category":"motorcycle_gasoline"}'
```

Associate the estimate to a confirmed contribution:

```bash theme={null}
curl -X POST "{baseUrl}/v1/impact-transactions/txn_01HZX6M4N5P6Q7R8S9T0U1V2/emissions-associations" \
  -H "X-API-Key: $AKHDAR_API_KEY" \
  -H "Idempotency-Key: idem_assoc_01HZX8A1B2C3D4E5F6G7H8" \
  -H "Content-Type: application/json" \
  -d '{"calculation_id":"calc_01HZX4K9M2Q8R7N6P5T4V3W2X1"}'
```

See [Delivery Emissions](/delivery-emissions).

## 4. Verify a webhook

Compute HMAC-SHA256 over the exact `X-Akhdar-Timestamp` value, a period (`.`), and the exact raw request body bytes. The signature format is `v1=<hex>`. Accept timestamps only within five minutes before or after receipt. Process idempotently by `event_id`.

See [Webhooks](/webhooks) for the confirmed-contribution payload and partner actions.