This API resolves an Iranian zipcode to a detailed postal address. A successful inquiry deducts the configured tariff from the caller's wallet and returns street, city, district, and additional address attributes provided by Sepal Yar.
POST/api/services/address-from-zipcode/
نیاز به احراز هویت
Token
60 requests/minute
مستندات
Overview
Overview
The Get Address From Zipcode API resolves an Iranian postal code to a structured address using Sepal Yar address data. Typical use cases include risk assessment, KYC address verification, and enriching customer profiles with accurate location details.
On each successful call, the service:
Validates the zipcode format
Queries Sepal Yar for detailed address attributes
Returns district, province, street, house number, and optional floor
Deducts the service tariff from the authenticated wallet
Stores a unique request_ref for auditing
Authentication
Authentication
This endpoint requires both a token and the user's unique code header.
502 Bad Gateway: Unexpected Sepal Yar outage or timeout
Always inspect the error payload for detailed error messages returned by Sepal Yar.
Best Practices
Best Practices
Pre-validate zipcode inputs on the client to reduce 400 responses.
Cache resolved addresses where appropriate to minimise repeated calls.
Monitor wallet balance and alert users before reaching zero.
Log request_ref values to reconcile billing.
Implement retry logic with exponential backoff for transient 5xx errors.
پارامترهای درخواست
پارامتر
نوع
اجباری
توضیحات
مثال
zipcode
String
اجباری
Iranian postal code (zipcode). Accepts 5 or 10 numeric characters. Whitespace or dash separators are removed automatically.
اعتبارسنجی: Must be numeric. Accepted lengths: 5 or 10 digits.
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Token YOUR_AUTH_TOKEN");
client.DefaultRequestHeaders.Add("X-Unique-Code", "YOUR_UNIQUE_CODE");
var payload = new
{
zipcode = "8831855356"
};
var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(
"https://inquiry.sepal.ir/api/services/address-from-zipcode/",
content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
}
}
