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

# AgriBackup EUDR API: Frequently Asked Questions (FAQ)

> Answers to common questions about EUDR compliance, polygon verification, DDS filing, webhooks, and the AgriBackup API.

Find answers to the most common questions about using AgriBackup for EUDR compliance. If your question isn't covered here, reach out to [support@agribackup.com](mailto:support@agribackup.com).

<AccordionGroup>
  <Accordion title="What commodities does EUDR apply to?">
    The EU Deforestation Regulation applies to seven commodity categories and all products derived from them:

    * **Cattle** (beef, leather, hides)
    * **Cocoa** (chocolate, cocoa butter, powder)
    * **Coffee**
    * **Palm oil** (palm kernel oil, fractions)
    * **Soy** (soy flour, soy oil, animal feed)
    * **Wood** (timber, paper, pulp, furniture, charcoal)
    * **Rubber** (natural rubber, tyres, gloves)

    Operators and traders placing these commodities on the EU market must ensure they are deforestation-free and legally produced. AgriBackup handles the due diligence and DDS filing requirements for all seven categories.
  </Accordion>

  <Accordion title="How long does polygon satellite verification take?">
    Satellite screening typically completes within **2–10 minutes** for standard polygon sets. Processing time depends on the number of polygons submitted, the total land area, and current satellite data availability.

    AgriBackup uses Sentinel-2 multispectral imagery processed through our NDVI analysis pipeline. Once screening is complete, a `polygon.verified` (or `polygon.failed`) webhook event is dispatched to your registered endpoint. You can also poll `GET /api/v1/enterprise/eudr/polygons/{polygonId}/status` at any time to check the current state.
  </Accordion>

  <Accordion title="Can I submit multiple polygons in one request?">
    Yes. The `POST /api/v1/enterprise/eudr/polygons` endpoint accepts a GeoJSON `FeatureCollection` containing multiple `Feature` objects. All features in the collection are processed as a single job and share one `jobId`.

    Each feature is assigned its own `polygonId` in the response once verification completes. You can then reference any subset of the returned `polygonId` values when registering a batch.
  </Accordion>

  <Accordion title="What happens if a polygon fails verification?">
    If a polygon fails satellite verification — for example, because deforestation indicators are detected — its `eudrStatus` is set to `HIGH_RISK` or `FAILED`. A `job.failed` webhook event fires if the entire ingestion job encounters a fatal error.

    Polygons that are not `COMPLIANT` cannot be referenced in a batch registration. You should investigate the specific failure reason returned in the polygon status response, and either correct the polygon geometry or engage your supplier to resolve the underlying compliance issue. Non-compliant polygons can be deleted and re-submitted after corrections.
  </Accordion>

  <Accordion title="What is a DDS and who needs to file one?">
    A Due Diligence Statement (DDS) is the formal declaration required by Article 4 of the EU Deforestation Regulation. It confirms that the commodity batch you are placing on the EU market is deforestation-free and legally produced.

    **Operators** (companies placing commodities on the EU market for the first time) must file a DDS before each shipment. **Traders** (downstream companies) must be able to reference the relevant DDS reference number.

    AgriBackup generates the DDS XML in TRACES NT format and submits it directly to the EU's TRACES NT system on your behalf, returning the official reference number.
  </Accordion>

  <Accordion title="How do I test without affecting real data or the blockchain?">
    Use the **sandbox environment** with a key prefixed `sk_test_`. The sandbox base URL is `https://sandbox.agribackup.com`.

    In the sandbox:

    * No real Hedera DLT transactions are created.
    * No real satellite imagery is queried (mock compliance responses are returned).
    * No DDS submissions reach the real TRACES NT system.

    Sandbox and production are fully isolated — your live data is never affected. See the [Environments](/reference/environments) page for setup details.
  </Accordion>

  <Accordion title="What is the difference between a batch and a shipment?">
    A **batch** represents a consolidated quantity of a commodity from one or more verified farm plots. It groups the agricultural origin data — polygons, supplier, harvest date, quantity — into a single traceable unit anchored on the Hedera ledger.

    A **shipment** represents the physical logistics movement of that commodity, identified by a Bill of Lading (BoL) reference number. Linking a batch to a shipment cryptographically ties the agricultural origin evidence to the shipping document, completing the chain of custody required by EUDR.

    One batch can be linked to one shipment. A shipment that spans multiple commodity origins would require multiple batches.
  </Accordion>

  <Accordion title="How are webhook payloads signed?">
    AgriBackup signs every webhook payload using **HMAC-SHA256**. The signature is sent in the `X-AgriBackup-Signature` HTTP header as a hex-encoded string.

    To verify a delivery:

    1. Extract the raw POST body as bytes (do not parse it first).
    2. Read the `X-AgriBackup-Signature` header.
    3. Compute `HMAC-SHA256(rawBody, signingSecret)` using your registered signing secret.
    4. Hex-encode the result.
    5. Use a constant-time comparison to check it matches the header value.

    Your signing secret is shown once when you register or rotate a webhook. Store it securely. See the [Webhooks Setup](/guides/webhooks-setup) guide for full code examples.
  </Accordion>

  <Accordion title="What happens to webhooks that fail delivery?">
    If your endpoint returns a non-2xx response or times out, AgriBackup retries delivery with exponential backoff for up to **72 hours**.

    After the retry window expires, the failed event is moved to the **Dead Letter Queue (DLQ)**. You can retrieve DLQ messages via `GET /api/v1/enterprise/eudr/webhooks/dlq`, replay them to trigger re-delivery, or acknowledge and delete them once processed.

    See the [Webhooks Setup](/guides/webhooks-setup) guide for DLQ management instructions.
  </Accordion>

  <Accordion title="Can I revoke a submitted DDS?">
    Yes. Use `POST /api/v1/enterprise/eudr/declarations/dds/{referenceId}/revoke`. AgriBackup will notify the TRACES NT system of the revocation.

    Note that revocation is **irreversible** — a revoked DDS cannot be reinstated. However, the original submission and the revocation action are both permanently recorded on the DLT audit trail. If you need to re-file, generate a new DDS.
  </Accordion>

  <Accordion title="What are idempotency keys and when should I use them?">
    An idempotency key is a unique string you supply in the `Idempotency-Key` request header. If AgriBackup receives two requests with the same key within 24 hours, the second request returns the same response as the first without performing the operation again.

    Use idempotency keys on all async ingestion endpoints — `POST /polygons`, `POST /batches`, and `POST /shipments/link` — to safely retry requests in the event of a network failure without creating duplicate records. Use a UUID or a deterministic key derived from your internal transaction ID.
  </Accordion>

  <Accordion title="What rate limits apply to the API?">
    The standard rate limit is **100 requests per second** for live API keys. Every response includes three headers:

    * `X-RateLimit-Limit` — your per-second allowance
    * `X-RateLimit-Remaining` — requests left in the current window
    * `X-RateLimit-Reset` — UTC epoch timestamp when the window resets

    If you exceed the limit, the API returns HTTP `429 Too Many Requests`. Implement exponential backoff before retrying. For higher throughput requirements, contact [support@agribackup.com](mailto:support@agribackup.com).
  </Accordion>
</AccordionGroup>