# Safra Partner API

> Official documentation for the Safra Partner API — machine-to-machine REST access for verified Safra bus companies in Syria.

- Base URL: https://safraway.com/api/partner/v1
- Version: 2026-08-21
- OpenAPI: https://docs.safraway.com/openapi.json
- HTML docs: https://docs.safraway.com/
- Full text: https://docs.safraway.com/llms-full.txt

## Docs

- [Overview](https://docs.safraway.com/index.md): Official Safra Partner API docs: authenticate with company secret keys, manage trips and bookings, and receive signed webhooks. REST v1 for verified companies.
- [Quickstart](https://docs.safraway.com/guides/quickstart.md): Issue a secret key, make one authenticated request, then wire bookings or webhooks. Staging and production are separate deployments with separate keys.
- [Authentication](https://docs.safraway.com/guides/authentication.md): Every Partner API call except the OpenAPI document requires a company secret key. HTTPS is required in production.
- [Scopes](https://docs.safraway.com/guides/scopes.md): Restricted keys only succeed on routes whose required scope is listed on the key. Empty scopes grant every Partner API operation.
- [Idempotency](https://docs.safraway.com/guides/idempotency.md): Writes may be retried. Send Idempotency-Key so Safra returns the original JSON instead of creating a second booking or webhook.
- [Errors](https://docs.safraway.com/guides/errors.md): Failures use a small JSON object: an error message and usually a machine-readable code. HTTP status is the first thing to branch on.
- [Pagination](https://docs.safraway.com/guides/pagination.md): List endpoints that can grow (trips, bookings, payments) return a meta object. Default page size is 25; the maximum is 100.
- [Rate limits](https://docs.safraway.com/guides/rate-limits.md): Two limiters run on Partner API routes: 60 requests per minute per IP before auth finishes, then 120 per minute per API key.
- [Versioning](https://docs.safraway.com/guides/versioning.md): The current Partner API version is 2026-08-21. Paths stay under /api/partner/v1. Additive fields may appear without a new version; breaking changes get a new prefix.
- [Webhooks](https://docs.safraway.com/guides/webhooks.md): Safra POSTs a signed JSON payload to your HTTPS URL when bookings, trips, schedules, or payments change. Verify the signature before you trust the body.
- [Booking lifecycle](https://docs.safraway.com/guides/booking-lifecycle.md): Partner bookings start as requested. Your staff (or your API) approve, reject, cancel, board, or mark no-show. Auto-approve is not implied.
- [API reference](https://docs.safraway.com/reference.md): Complete Safra Partner API v1 reference: 51 REST endpoints, scopes, fields, and curl examples. Base URL https://safraway.com/api/partner/v1.

## Optional

- [OpenAPI 3.1 JSON](https://docs.safraway.com/openapi.json)
- [Company dashboard (create keys)](https://safraway.com/company/developers)