Versions and changelog

The v1 in the path

https://api.fatureihoje.com/public/v1/me

The v1 is the version of the contract, not the version of the program. The program behind it changes; what v1 promises does not.

While the path says v1, what already exists keeps existing, with the same name, the same type and the same meaning.

What is additive

These changes land in v1 at any time, with no notice:

• A new field in a response. A response may gain fields you have never seen.
• A new route. An area that did not answer starts answering.
• A new event.
• A new filter or a new query parameter, always optional.
• A new enum value. A status field may start returning a value that did not exist.

None of them breaks an existing integration, as long as your client follows three rules.

The three rules of a client that does not break

1. Ignore a field you do not know. Read the fields you use and let the rest through. Validation that rejects the whole response because of an unknown field breaks on the first new field.
2. Tolerate an unknown enum value. Treat a value you do not recognize as “other” instead of throwing. A switch with no default case is the most common failure here.
3. Do not depend on the text. The order of the JSON fields and the text of message are not contract. What is contract is described in Errors.

What breaks

These changes do not happen in v1. They would only exist in a /public/v2:

• removing or renaming a field of a response;
• changing the type of a field;
• making a field that was optional required in a request;
• no longer accepting a value that was accepted;
• changing the meaning of a field, even keeping name and type;
• removing a route.

The automatic lock

This is not only a written promise. The published v1 contract is kept in our repository, and an automatic check compares the contract of the code against that file. It lists, field by field, what disappeared, what changed type, what became required and what stopped being accepted, and it blocks the change before it reaches production. It runs in the commit hook for anyone touching the contract and, above all, inside the process that builds the published version of the API: no version reaches production without passing it.

A second check guarantees the other side: the v1 response schemas are not closed. That is what makes “a new field does not break” true rather than a writing style, because a closed schema would reject its own response as soon as it gained a field.

When a /public/v2 exists

It does not exist yet, and no route is being deprecated.

When that changes, v1 does not go down along with the arrival of v2. The plan is to warn through two channels:

• the Deprecation and Sunset headers on the responses of the route on its way out, with the date;
• an e-mail to the owners of the active API keys.

Neither header shows up in any response today, precisely because nothing is being deprecated. The overlap period between v1 and v2 will be announced together with v2, here on this page.

How you find out what changed

• This page. The changelog lives here, in the section below.
• The Reference. It is generated from the API code, so it never lists a route that does not exist and never hides one that does. It is the most current source of what answers today.
• E-mail, in the cases that require action from you, such as a deprecation.

If your integration matters to your business, it is worth checking the Reference from time to time. A new field breaks nothing, but it is often exactly what you were waiting for.

Changelog

Each entry has the date, what changed, and whether it requires action from an existing integration. The field-by-field list of what the API answers is always the Reference.

v1 | to be published

The first public version of the contract. The date goes here on the day v1 is published. No action required: there is no earlier version.

What v1 includes:

• Account: GET /public/v1/me, with the company, the key’s permissions, the member it acts as, and the request limit.
• Clients, with their addresses, and leads, with the contact task.
• Team, tasks, and appointments.
• Service orders, with service order types and the status, start, complete, and cancel actions, and quotes, with send, approve, reject, cancel, and conversion into a sale or a service order.
• Sales, with versions, payments, payment reversals, installment rescheduling, and cancellation.
• Finance: transactions (including transfers, recurring entries, and installments), accounts, and categories.
• Products, with variations and categories, read-only stock (balance and ledger), and services, with categories.
• Webhooks: endpoint registration, secret and rotation, ping, delivery log, redelivery, and the list of events from the last 30 days, with the Event catalog.
• What applies to every area: cursor pagination, errors with stable codes, idempotency on every POST, and per-plan rate limits.

Next step

• Errors: why code is stable and message is not.
• Overview: what is live today and what arrives in the next phases.