Versioning and compatibility

The API version is in the URL: https://api.cartaflow.com.br/v1. Everything these docs describe is version 1.

What changes without noticeCopy Anchor Link

These changes do not break a well-built integration, so they happen within version 1, at any time:

• new endpoints;
• new optional request fields;
• new fields in responses and events;
• new values in fields with a list of values, such as a new status;
• new event types;
• new error and detail codes;
• changes to the wording of message.

They are all listed in the Changelog.

Prepare your integrationCopy Anchor Link

So that these changes never break anything:

• Ignore fields you do not know. Do not fail when a response or an event has a new field. Avoid validating responses against a schema that rejects extra fields.
• Handle unknown values. When reading status, type or cancellation_reason, have a path for a value you do not know yet: log it and move on instead of crashing. An unknown status can be treated as "in progress".
• Handle errors by code and, if the code is unknown, by type. See Errors.
• Do not match on the text of message. It can change.
• Subscribe to the events you use in the dashboard instead of accepting every event. That way a new type does not reach your server unless you ask for it.

What only changes in a new versionCopy Anchor Link

Changes that can break an integration only happen in a new version with a different prefix, such as /v2. For example:

• removing or renaming an endpoint, a field or a value;
• making an optional field required;
• changing the type or the meaning of a field;
• changing the error format.

When a new version comes out, the previous one keeps working for at least 12 months. We email the technical contacts of every account still on the previous version, with what changes and how to migrate.