Skip to main content

Getting started

1. Request access​

Only the owner or an admin of the organization can do this, and the organization needs an active subscription.

  1. Sign in at validades.com and select the organization.
  2. Open Team → API → Manage API.
  3. 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:

  1. Click Create key.
  2. Give it a name that identifies the integration (for example, "Downtown store ERP").
  3. Choose the access:
    • Read only (read): queries only;
    • Read and write (read and write): queries, creating and updating;
    • Allow deletions (delete): check it only if the integration needs to delete data.
  4. 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​