ChangesChangelog

Changelog

Conta Simples API change history

For conventions, versioning, and breaking change policy, see Changelog conventions.

[2026-09-03]

🚧 This whole entry covers the VCN endpoints, still unavailable in Sandbox and Production. No existing integration is affected.

Changed

  • Error texts aligned with what the API actually returns. No code changed — it was the message examples that were stale. Always branch on the code, never on the text.
    • 409 vcn-not-active → The VCN is not active and cannot be updated.
    • 409 vcn-not-updatable → This VCN type does not accept updates.
    • 503 vcn-provider-unavailable → The VCN update could not be completed; retry the request.
    • 400 invalid-vcn-request → Unable to issue a VCN for this request: {reason}, where the reason is a sentence describing the rule that failed. The prefix is the same on both routes, Update VCN included: the text says “issue a VCN” even on a PATCH, which issues nothing. That is the service's real behaviour, not a documentation slip — one more reason to branch on the code.
    • 500 internal-exception → Aconteceu um erro. The text is fixed and does not describe the failure: the original message is suppressed on purpose, so no internal detail leaks.
  • The 400 on Update VCN now distinguishes two code values. An endDate in the past or beyond 365 days from issuance arrives as invalid-vcn-request, not as bad-request-exception: those two rules live in the controls derivation, not in the schema, so they come without errors[].
  • The request and response amount are now separate schemas. They were the same one, which is why fees showed as optional on both sides. In the request it stays optional (omitting it means 0.00); in the response it is now required (AmountResponse), because the service applies the default at issuance and the field always comes back filled. Clients generated from the spec no longer get fees as optional in the response.
  • The 400 active-funding-card-not-found message on Create VCN is now generic: There is no active funding card. Check the request or provision the company for this combination, then retry. It previously named the requested type and the integrator platform. The code does not change — branch on it, never on the message text.

Removed

  • partner is gone from the Create VCN response. The field identified the integrator platform resolved from your credential and was echoed back so you could confirm which partner the issuance landed on. It is internal Conta Simples data and is no longer published: the partner is the one on your own credential, so the response added nothing you did not already have.
    • Nothing changes in the request: partner was never accepted in the body, and still is not.
    • Supersedes the partner announced in [2026-09-01], which documented it as echoed in the response.
    • The other responses on this resource never carried the field: Update VCN returns five fields and Reveal VCN data returns three.

[2026-09-02]

Added

  • startDate in the Create VCN body, optional, as a pure YYYY-MM-DD date: for a card that only becomes valid on a future day. Omitted, the window opens at the moment of issuance — the behavior it always had. Sent, it cannot fall on a day before the issuance day, and endDate must come after it.
    • The 365-day cap counts from issuance, not from the startDate you send: postponing the start does not extend the cap.
    • The endDate defaults did not change: HOTEL = checkOut + 20 days · AERIAL = issuance + 1 day · CUSTOM = issuance + 60 days.
    • Update VCN does not accept startDate: moving the start of a live window is a different operation.

Changed

  • VCN date fields standardized in both directions. The usage window is called startDate/endDate in the request and in the response, on both endpoints. Coming soon — the endpoints remain unavailable in Sandbox and Production, with no impact on existing integrations.
    • In Create VCN, the body's expirationDate is now endDate.
    • In Update VCN, the expirationDate in the body and in the response is now endDate.
    • startDate and endDate in the Create VCN response now come as pure YYYY-MM-DD dates, no longer as an instant with a time (2026-10-08T00:00:00.000Z → 2026-10-08). The time never carried information: the network rejects date-times on these fields, so the effective value was always the date.
    • Before, you sent expirationDate and got the same value back as endDate, at a different precision — and the same response also carried a second expirationDate, which is the physical card expiration. That is the only expirationDate left, inside the card block.
  • VCN card expiration standardized on MM/YYYY — two-digit month and four-digit year (e.g. 06/2031). Applies to card.expirationDate in Create VCN and to expirationDate in Reveal VCN data, which the docs declared as MM/YY (06/31). It is the same format already used by formattedExpirationDate on the cards resource. Coming soon — both endpoints remain unavailable in Sandbox and Production, with no impact on existing integrations.
    • This does not change the VCN usage window, which travels in the Create VCN body and in the Update VCN body: it stays a pure date and is now called endDate, per the entry above.

Removed

  • vcnLast4 is gone from the Create VCN response. The same response already returns the full pan in the card block, which the four digits are derived from. It was also the only place in the contract that exposed them: the Update VCN response never carried them, and Reveal VCN data returns only pan, cvv and expirationDate. For reconciliation, slice the last four digits off the pan at issuance and keep them on your side.

[2026-09-01]

Changed

  • Create VCN (POST /credit-cards/v1/vcns): second pre-launch contract revision. See reference. Main changes:
    • obt leaves the body: the integrator platform is now resolved from the credential and echoed back in the response's partner field — the partner does not send it.
    • New CUSTOM type: a card for a use the partner defines (e.g. one card per supplier), with a reference block (reference.id as the idempotency key), the ceiling sent in limit {value, currency} (minimum 0.01), a 60-day default validity and up to 10,000 transactions by default. For CUSTOM, amount is forbidden; for booking types, limit is forbidden.
    • Optional expirationDate on all three types: when sent, it takes precedence over the derived validity; capped at 365 days from issuance.
    • Response: spendLimit (number) is replaced by the limit {value, currency} block, uniform across the three types; maxPurchaseQuantity is now always returned with the effective value; maxPurchaseQuantity gains a 100,000 cap.
    • Errors: the invalid-booking-for-vcn code was renamed to invalid-vcn-request.
  • Reveal VCN card data: the resource moves from GET /credit-cards/v1/vcns/{vcnId}/card to GET /credit-cards/v1/vcns/{vcnId}/reveal (the old link redirects); the response keeps pan, cvv and expirationDate at the top level, and the holderName field is gone; the 404 now uses the VCN error envelope (vcn-not-found).

Added

  • Update VCN endpoint (PATCH /credit-cards/v1/vcns/{vcnId}): ceiling top-up and validity extension/shortening for CUSTOM VCNs, without swapping the card. limit.value is the window's accumulated ceiling (not a balance, not an increment) and there is an optional compare-and-set via limit.expectedValue. AERIAL and HOTEL VCNs are not updatable. Coming soon — not yet available in Sandbox/Production.
  • Adds the update banking transaction endpoint (PATCH /statements/v1/banking/{transactionId}): update notes, category, cost center, and reconcile a transaction on the banking statement. See reference.

[2026-08-21]

Changed

  • Create VCN (POST /credit-cards/v1/vcns): contract revised before launch — the published documentation fully replaces the previous version. See reference. Coming soon — the endpoint was never available in Sandbox or Production, so there is no impact on existing integrations. Main changes:
    • Identification: type is now HOTEL | AERIAL (was AIR); the OBT identifier becomes the obt body field and replaces the X-Origin header. The {type, obt} pair, enabled at onboarding, determines which card is used for issuance — the partner does not send a provider.
    • Idempotency: the root bookingId and the Idempotency-Key header are gone; the key is now hotelBooking.reservationId (HOTEL) or flightBooking.recordLocator (AERIAL). 409 happens while the key has a live VCN (ACTIVE or BLOCKED inside its validity window); once expired or cancelled, a new issuance replaces it.
    • Booking blocks: hotelBooking.guests is now the guest list (name/surname), confirmationId became reservationId, flightBooking now describes the ticket (recordLocator, passenger, legs) and customFields uses name/value/dataType. requestor is now required.
    • Response: returns obt, vcnLast4, startDate, endDate, spendLimit and the echo of the booking block, replacing the controls object.
    • Amounts and errors: monetary values are decimal with at most 2 places, end to end — more than 2 places is rejected with 400. On validation failures, each field in errors[] is prefixed by the request part (body.).

Removed

  • Documentation for listing VCN transactions (GET /credit-cards/v1/vcns/{vcnId}/transactions): pulled from the reference while the launch is on hold. The endpoint was never available in Sandbox or Production; we will republish the documentation when the launch resumes.
  • mTLS requirement on the VCN endpoints and the mTLS Connection page: discontinued before launch — the VCN endpoints use the API's standard authentication (API key/secret → Bearer token).

[2026-08-03]

Added

  • Banking transaction receipt endpoint (GET /statements/v1/banking/{transactionId}/receipt): generates the PDF receipt of a banking transaction (PIX, TED, transfer between Conta Simples accounts, or bill payment) and returns a short-lived signed URL (5 minutes) for download. Available only for transactions with status PROCESSED (status: 2); check the transaction's showReceipt field before calling. See reference.

[2026-06-30]

Added

  • Link receipt or invoice endpoint (POST /attachments/v1): creates an attachment record linked to an existing transaction and returns a presigned URL for direct S3 upload. 2-step flow: (1) POST to get {id, uploadUrl}; (2) PUT {uploadUrl} with the file binary. The returned id is compatible with GET /attachments/v1/content/{attachmentId}. See reference.

[2026-06-29]

Added

  • List bills endpoint (GET /credit-cards/v1/bills): lists all credit card bills for the authenticated company, with an optional status filter. Amounts are in BRL. See reference.
  • Bill details endpoint (GET /credit-cards/v1/bills/{dueDate}): returns the totals (domestic, international, IOF, credits, and charges) and the items (transactions) of a specific bill, identified by its due date. See reference.

[2026-06-28]

Added

  • Reveal VCN card data endpoint (GET /credit-cards/v1/vcns/{vcnId}/card): returns PAN, CVV and expiration of an already-issued VCN, identified by vcnId; the CVV is not stored. See reference. Coming soon — not yet available in Sandbox/Production.
  • List VCN transactions endpoint (GET /credit-cards/v1/vcns/{vcnId}/transactions): paginated list of a VCN's transactions, ordered by date descending, with status and period filters. Coming soon — documentation pulled on 2026-08-21 while the launch is on hold (see [2026-08-21]).

[2026-06-26]

Added

  • Create VCN endpoint (POST /credit-cards/v1/vcns): issues a virtual card (VCN) for travel bookings (hotel and air) with the booking metadata, returning PAN, CVV and expiration. See reference. Coming soon — not yet available in Sandbox/Production.
  • Get account balance endpoint (GET /accounts/v1/balance): returns the available balance for the authenticated company's account in BRL. See reference.

[2026-06-23]

Added

  • Create cost center endpoint (POST /cost-centers/v1/cost-centers): creates a new cost center for the company; name is required and must be unique per company. See reference.
  • Get cost center by ID endpoint (GET /cost-centers/v1/cost-centers/{id}): returns the data of a specific cost center by UUID. See reference.
  • Update cost center endpoint (PATCH /cost-centers/v1/cost-centers/{id}): renames an existing cost center; the new name must be unique within the company. See reference.
  • Delete cost center endpoint (DELETE /cost-centers/v1/cost-centers/{id}): deletes a cost center by UUID; returns 204 on success. See reference.

Deprecated

  • responsible field in GET /cost-centers/v1/cost-centers response: will be removed in a future version. Do not use this field in new integrations. See reference.

[2026-06-18]

Added

  • Update supplier endpoint (PUT /suppliers/v1/suppliers/{id}): updates the name of an existing company supplier; the name field is required and must be unique per company. See reference.
  • Delete supplier endpoint (DELETE /suppliers/v1/suppliers/{id}): deletes an existing company supplier by numeric ID. Returns 204 on success. See reference.

[2026-06-11]

Added

  • Update category name endpoint (PATCH /categories/v1/categories/{id}): renames an existing custom category; only the name field is updated — linked establishments and category type remain unchanged. The new name must be unique within the company. See reference.
  • Delete categories endpoint (DELETE /categories/v1/categories): deletes one or more custom categories in a single request. If a category has linked establishments, supply moveTo to reassign them before deletion — omitting it returns 422. See reference.

[2026-06-03]

Added

  • Partial user update endpoint (PATCH /users/v1/users/{userId}): updates name and/or roleId for an active company user; at least one field required per request. See reference.
  • Adds supplier list endpoint (GET /suppliers/v1/suppliers). See reference.
  • Adds get supplier by ID endpoint (GET /suppliers/v1/suppliers/{id}). See reference.
  • Adds create supplier endpoint (POST /suppliers/v1/suppliers). See reference.

[2026-05-28]

Added

  • List cost centers endpoint (GET /cost-centers/v1/cost-centers): returns all cost centers for the authenticated company. The response includes id, name, companyId, and the optional responsible field with the name and ID of the assigned owner. See reference.

Changed

  • Endpoint PATCH /statements/v1/credit-card/{transactionId}: added costCenterId (UUID) field to classify the transaction by cost center. See reference.

[2026-05-27]

Added

  • Get user by ID endpoint (GET /users/v1/users/{userId}): returns details of a specific company user by UUID v4 identifier; response matches the list item structure (UserDto), with 404 when the user does not belong to the authenticated company.

[2026-05-26]

Added

  • Update card transaction endpoint (PATCH /statements/v1/credit-card/{transactionId}): updates notes, isConciled, and categoryId on a credit card transaction; at least one field required per request.

[2026-05-14]

Changed

  • Card statement endpoint (GET /statements/v1/credit-card): added optional cardIds query parameter (comma-separated string) to filter transactions by one or more cards at once.

[2026-04-28]

Added

  • Create category endpoint (POST /categories/v1/categories): creates a custom category for the company; the name must be unique among the company’s categories.
  • Get category by ID endpoint (GET /categories/v1/categories/{id}): returns a company category by numeric ID; response matches list items (establishments and type).

[2026-04-17]

Added

  • List categories endpoint (GET /categories/v1/categories): returns categories available to the company.

[2026-04-10]

Added

  • Banking statement endpoint (GET /statements/v1/banking): paginated company bank transactions with filters by period, account, category, cost center, status, amount, and responsible user.

[2026-04-02]

Changed

  • Card statement response (GET /statements/v1/credit-card): each item in attachments may include an optional type field with the MIME type (image/jpeg, image/png, or application/pdf) when the file name extension is recognized.

[2026-03-27]

Added

  • Delete user endpoint (DELETE /users/v1/users/{userId}): removes a user from the company by ID.

[2026-03-25]

Added

  • Create user invites endpoint (POST /users/v1/invites): send invites for new users to join the company with email and role.

[2026-03-24]

Added

  • List roles endpoint (/users/v1/roles): returns company roles with profile, permissions (claims), and linked user counts.

[2026-03-23]

Added

  • List user invites endpoint (/users/v1/invites): paginated invites with filters by status and role.

[2026-03-17]

Changed

  • Card statement (/statements/v1/credit-card): documentation updated from POST to GET, with filter parameters (limit, startDate, endDate, types, nextPageStartKey) sent in the query string.

[2026-03-16]

Added

  • Corporate card management endpoints: list with filters, block, and unblock cards.
  • List company users endpoint, with email filter and cursor-based pagination.

[2026-02-25]

Added

  • List credit cards endpoint.

[2026-02-09]

Added

  • Login endpoint for Conta Simples API authentication.

[2026-02-03]

Added

  • Endpoint to download transaction attachments.

[2026-01-19]

Added

  • Card statement endpoint extended with new fields related to attachments.

[2025-10-15]

Added

  • Card statement endpoint.
  • Initial API schema definition for transactions and cards.
Was this page helpful?