Getting started
1. Request access
Only the owner or an admin of the organization can do this, and the organization needs an active subscription.
- Sign in at validades.com and select the organization.
- Open Team → API → Manage API.
- Click Request access, read and accept the API Terms of Use and, if you want, tell us what you will use the API for.
Our team reviews the request and lets you know by email. If the request is not approved, a new request can be made after 30 days.
2. Create a key
Once the API is enabled, in the same panel:
- Click Create key.
- Give it a name that identifies the integration (for example, "Downtown store ERP").
- Choose the access:
- Read only (
read): queries only; - Read and write (
readandwrite): queries, creating and updating; - Allow deletions (
delete): check it only if the integration needs to delete data.
- Read only (
- Choose an expiration (optional) and confirm.
The key is shown only once. Copy it and keep it in a safe place, such as your server's secret manager. If you lose the key, revoke it and create another one. Each organization can have up to 5 active keys.
The owner and admins get an email whenever a key is created.
3. Test the key
The /v1/me route shows who the key belongs to, the limits and the usage of the month:
curl https://api.validades.com/v1/me \
-H "Authorization: Bearer vld_live_YOUR_KEY"
{
"data": {
"organization": { "id": "8f1c…", "name": "Example Market" },
"workspace": { "id": "2b6f…" },
"api_key": {
"id": "0d3e…",
"name": "Downtown store ERP",
"last_four": "a9F2",
"scopes": ["read", "write"],
"expires_at": null,
"created_at": "2026-11-07T12:00:00.000Z"
},
"limits": {
"key_requests_per_minute": 60,
"organization_requests_per_minute": 120,
"monthly_quota": 50000
},
"usage": {
"month": { "period": "2026-11", "used": 1, "remaining": 49999, "resets_at": "2026-12-01T00:00:00.000Z" },
"today": { "date": "2026-11-07", "used": 1 }
}
}
}
4. Make your first calls
List the batches that expire by the end of the month:
curl "https://api.validades.com/v1/batches?exp_date_to=2026-11-30&limit=100" \
-H "Authorization: Bearer vld_live_YOUR_KEY"
Create a product (needs the write scope):
curl -X POST https://api.validades.com/v1/products \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: erp-product-7891234567890" \
-d '{"name": "Whole milk 1L", "code": "7891234567890", "days_to_be_next": 15}'
Create a batch for that product:
curl -X POST https://api.validades.com/v1/products/PRODUCT_ID/batches \
-H "Authorization: Bearer vld_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"exp_date": "2026-12-31", "amount": 24, "price": 6.49}'
Next steps
- Understand the limits and quota before putting the integration in production.
- To keep another system up to date, see Pagination and sync.
- Handle errors by the
codefield, which never changes. - Follow the calls in the panel: see Logs and usage.