Changelog

Histórico de mudanças da API Conta Simples

Para entender as convenções, versionamento e política de breaking changes, veja Convenções do Changelog.

[2026-09-03]

🚧 Toda esta entrada trata dos endpoints de VCN, ainda indisponíveis em Sandbox e Produção. Nenhuma integração existente é afetada.

Changed

Textos de erro alinhados ao que a API realmente devolve. Nenhum code mudou — os exemplos de message é que estavam desatualizados. Ramifique sempre pelo code, nunca pelo texto.
- 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: {motivo}, onde o motivo é uma frase que descreve a regra violada. O prefixo é o mesmo nas duas rotas, inclusive em Atualizar VCN: o texto diz “issue a VCN” mesmo num PATCH, que não emite nada. É o comportamento real do serviço, não erro de documentação — mais um motivo para ramificar pelo code.
- 500 internal-exception → Aconteceu um erro. O texto é fixo e não descreve a falha: a mensagem original é suprimida de propósito, para não expor detalhe interno.
400 de Atualizar VCN passa a distinguir dois code. endDate no passado ou além de 365 dias da emissão chega como invalid-vcn-request, e não como bad-request-exception: essas duas regras vivem na derivação dos controles, não no schema, então vêm sem errors[].
amount do pedido e da resposta agora são schemas separados. Eram o mesmo, e por isso fees aparecia como opcional nos dois lados. No pedido segue opcional (omitir significa 0.00); na resposta virou obrigatório (AmountResponse), porque o serviço aplica o default na emissão e o campo sempre volta preenchido. Quem gera cliente a partir do spec deixa de receber fees como opcional na resposta.
Mensagem do 400 active-funding-card-not-found em Criar VCN agora é genérica: There is no active funding card. Check the request or provision the company for this combination, then retry.. Antes o texto nomeava o type do pedido e a plataforma integradora. O code não muda — ramifique por ele, nunca pelo texto da mensagem.

Removed

partner sai da resposta de Criar VCN. O campo identificava a plataforma integradora resolvida da sua credencial e vinha ecoado para você conferir em qual parceiro a emissão caiu. Ele é dado interno da Conta Simples e deixa de ser publicado: o partner é o da sua própria credencial, então a resposta não acrescentava informação que você já não tivesse.
- Nada muda no pedido: partner nunca foi aceito no corpo, e continua não sendo.
- Supera o partner anunciado em [2026-09-01], que o documentava como ecoado na resposta.
- As demais respostas do recurso não traziam o campo: Atualizar VCN devolve cinco campos e Revelar dados do VCN devolve três.

[2026-09-02]

Added

startDate no corpo de Criar VCN, opcional, em data pura YYYY-MM-DD: para o cartão que só passa a valer num dia futuro. Omitido, a janela abre no instante da emissão — o comportamento de sempre. Informado, não pode ser um dia anterior ao da emissão, e o endDate tem de ser posterior a ele.
- O teto de 365 dias conta da emissão, e não do startDate informado: adiar o início não estende o teto.
- Os defaults de endDate não mudaram: HOTEL = checkOut + 20 dias · AERIAL = emissão + 1 dia · CUSTOM = emissão + 60 dias.
- Atualizar VCN não aceita startDate: mover o início de uma janela viva é outra operação.

Changed

Campos de data do VCN padronizados nas duas direções. A janela de uso se chama startDate/endDate no pedido e na resposta, nos dois endpoints. Em breve — os endpoints seguem indisponíveis em Sandbox e Produção, sem impacto em integrações existentes.
- Em Criar VCN, o expirationDate do corpo passa a se chamar endDate.
- Em Atualizar VCN, o expirationDate do corpo e da resposta passa a se chamar endDate.
- startDate e endDate da resposta de Criar VCN passam a vir em data pura YYYY-MM-DD, e não mais como instante com hora (2026-10-08T00:00:00.000Z → 2026-10-08). A hora nunca carregou informação: a bandeira recusa data-hora nesses campos, então o valor efetivo sempre foi a data.
- Antes, você enviava expirationDate e recebia o mesmo dado de volta como endDate, com outra precisão — e na mesma resposta havia um segundo expirationDate, que é a validade física do cartão. O único expirationDate que resta é esse, dentro do bloco card.
Validade do cartão do VCN padronizada em MM/YYYY — mês com dois dígitos e ano com quatro (ex.: 06/2031). Vale para o card.expirationDate de Criar VCN e para o expirationDate de Revelar dados do VCN, que a documentação declarava em MM/AA (06/31). É o mesmo formato já usado em formattedExpirationDate no recurso de cartões. Em breve — os dois endpoints seguem indisponíveis em Sandbox e Produção, sem impacto em integrações existentes.
- Não muda a janela de uso da VCN, que viaja no corpo de Criar VCN e no de Atualizar VCN: ela segue em data pura e passou a se chamar endDate, conforme a entrada acima.

Removed

vcnLast4 sai da resposta de Criar VCN. A mesma resposta já entrega o pan completo no bloco card, de onde os quatro dígitos são derivados. Era também o único ponto do contrato que os expunha: a resposta de Atualizar VCN nunca os trouxe, e Revelar dados do VCN devolve apenas pan, cvv e expirationDate. Para conciliação, recorte os quatro últimos dígitos do pan na emissão e guarde-os do seu lado.

[2026-09-01]

Changed

Criar VCN (POST /credit-cards/v1/vcns): segunda revisão pré-lançamento do contrato. Ver referência. Principais mudanças:
- obt sai do corpo: a plataforma integradora passa a ser resolvida da credencial e volta ecoada no campo partner da resposta — o parceiro não a envia.
- Novo tipo CUSTOM: cartão para um uso definido pelo parceiro (ex.: um cartão por fornecedor), com bloco reference (reference.id como chave de idempotência), teto informado em limit {value, currency} (mínimo 0.01), validade default de 60 dias e até 10.000 transações por padrão. Em CUSTOM, amount é proibido; nos tipos de reserva, limit é proibido.
- expirationDate opcional nos três tipos: quando informado, prevalece sobre a validade derivada; teto de 365 dias da emissão.
- Resposta: spendLimit (número) dá lugar ao bloco limit {value, currency}, uniforme nos três tipos; maxPurchaseQuantity passa a vir sempre, com o valor efetivo; maxPurchaseQuantity ganha teto de 100.000.
- Erros: o code invalid-booking-for-vcn foi renomeado para invalid-vcn-request.
Revelar dados do VCN: o recurso muda de GET /credit-cards/v1/vcns/{vcnId}/card para GET /credit-cards/v1/vcns/{vcnId}/reveal (o link antigo redireciona); a resposta segue com pan, cvv e expirationDate no topo, e o campo holderName sai; o 404 passa a usar o envelope de erro de VCN (vcn-not-found).

Added

Endpoint de atualização de VCN (PATCH /credit-cards/v1/vcns/{vcnId}): recarga de teto e prorrogação/encurtamento de validade para VCNs CUSTOM, sem trocar o cartão. O limit.value é o teto acumulado da janela (não é saldo nem incremento) e há compare-and-set opcional via limit.expectedValue. VCNs AERIAL e HOTEL não são atualizáveis. Em breve — ainda não disponível em Sandbox/Produção.
Adiciona endpoint de atualização de transação bancária (PATCH /statements/v1/banking/{transactionId}): permite atualizar observação, categoria, centro de custo e conciliar uma transação do extrato bancário. Ver referência.

[2026-08-21]

Changed

Criar VCN (POST /credit-cards/v1/vcns): contrato revisado antes do lançamento — a documentação publicada substitui integralmente a versão anterior. Ver referência. Em breve — o endpoint nunca esteve disponível em Sandbox nem Produção, portanto não há impacto em integrações existentes. Principais mudanças:
- Identificação: type passa a ser HOTEL | AERIAL (era AIR); o identificador da OBT vira o campo obt no corpo e substitui o header X-Origin. O par {type, obt}, habilitado no onboarding, direciona a emissão — o parceiro não informa provedor.
- Idempotência: saem o bookingId da raiz e o header Idempotency-Key; a chave passa a ser hotelBooking.reservationId (HOTEL) ou flightBooking.recordLocator (AERIAL). O 409 ocorre enquanto a chave tem um VCN vivo (ACTIVE ou BLOCKED dentro da janela de validade); expirado ou cancelado, uma nova emissão o substitui.
- Blocos de reserva: hotelBooking.guests passa a ser a lista de hóspedes (name/surname), confirmationId virou reservationId, flightBooking passa a descrever o bilhete (recordLocator, passageiro, trechos) e customFields usa name/value/dataType. requestor passa a ser obrigatório.
- Resposta: traz obt, vcnLast4, startDate, endDate, spendLimit e o eco do bloco de reserva, no lugar do objeto controls.
- Valores e erros: valores monetários em decimal com no máximo 2 casas, ponta a ponta — mais de 2 casas é recusado com 400. Em falhas de validação, cada field de errors[] vem prefixado pela parte da requisição (body.).

Removed

Documentação da consulta de transações do VCN (GET /credit-cards/v1/vcns/{vcnId}/transactions): retirada da referência enquanto o lançamento está em espera. O endpoint nunca esteve disponível em Sandbox nem Produção; republicaremos a documentação quando o lançamento for retomado.
Exigência de mTLS nos endpoints de VCN e a página Conexão mTLS: descontinuadas antes do lançamento — os endpoints de VCN usam a autenticação padrão da API (API key/secret → token Bearer).

[2026-08-03]

Added

Endpoint de comprovante de transação bancária (GET /statements/v1/banking/{transactionId}/receipt): gera o comprovante em PDF de uma transação bancária (PIX, TED, transferência entre contas Conta Simples ou pagamento de boleto) e retorna uma URL assinada de curta duração (5 minutos) para download. Disponível apenas para transações com status PROCESSADO (status: 2); consulte o campo showReceipt da transação antes de chamar. Ver referência.

[2026-06-30]

Added

Endpoint de vinculação de comprovante ou nota fiscal (POST /attachments/v1): cria um registro de anexo vinculado a uma transação existente e retorna uma URL pré-assinada para upload direto ao S3. Fluxo em 2 etapas: (1) POST para obter {id, uploadUrl}; (2) PUT {uploadUrl} com o binário do arquivo. O id retornado é compatível com GET /attachments/v1/content/{attachmentId}. Ver referência.

[2026-06-29]

Added

Adiciona endpoint de listagem de faturas (GET /credit-cards/v1/bills): lista todas as faturas de cartão de crédito da empresa autenticada, com filtro opcional por status. Os valores são em BRL. Ver referência.
Adiciona endpoint de detalhes da fatura (GET /credit-cards/v1/bills/{dueDate}): retorna os totalizadores (nacional, internacional, IOF, créditos e encargos) e os itens (transações) de uma fatura específica, identificada pela data de vencimento. Ver referência.

[2026-06-28]

Added

Adiciona endpoint de revelar dados do VCN (GET /credit-cards/v1/vcns/{vcnId}/card): retorna PAN, CVV e validade de um VCN já emitido, identificado pelo vcnId; o CVV não fica armazenado. Ver referência. Em breve — ainda não disponível em Sandbox/Produção.
Adiciona endpoint de consulta de transações do VCN (GET /credit-cards/v1/vcns/{vcnId}/transactions): lista paginada das transações de um VCN, ordenada por data decrescente, com filtros de status e período. Em breve — documentação retirada em 21/08/2026 enquanto o lançamento está em espera (ver [2026-08-21]).

[2026-06-26]

Added

Adiciona endpoint de criação de VCN (POST /credit-cards/v1/vcns): emite um cartão virtual (VCN) para reservas de turismo (hotel e aéreo) com os metadados da reserva, retornando PAN, CVV e validade. Ver referência. Em breve — ainda não disponível em Sandbox/Produção.
Endpoint de consulta de saldo da conta (GET /accounts/v1/balance): retorna o saldo disponível da conta da empresa autenticada em BRL. Ver referência.

[2026-06-23]

Added

Endpoint de criação de centro de custo (POST /cost-centers/v1/cost-centers): cria um novo centro de custo para a empresa; o campo name é obrigatório e deve ser único por empresa. Ver referência.
Endpoint de consulta de centro de custo por ID (GET /cost-centers/v1/cost-centers/{id}): retorna os dados de um centro de custo específico pelo UUID. Ver referência.
Endpoint de atualização de centro de custo (PATCH /cost-centers/v1/cost-centers/{id}): renomeia um centro de custo existente; o novo nome deve ser único na empresa. Ver referência.
Endpoint de exclusão de centro de custo (DELETE /cost-centers/v1/cost-centers/{id}): exclui um centro de custo pelo UUID; retorna 204 em caso de sucesso. Ver referência.

Deprecated

Campo responsible na resposta de GET /cost-centers/v1/cost-centers: será removido em versão futura. Não utilize este campo em novas integrações. Ver referência.

[2026-06-18]

Added

Endpoint de atualização de fornecedor (PUT /suppliers/v1/suppliers/{id}): atualiza o nome de um fornecedor existente da empresa; o campo name é obrigatório e deve ser único por empresa. Ver referência.
Endpoint de exclusão de fornecedor (DELETE /suppliers/v1/suppliers/{id}): exclui um fornecedor existente da empresa pelo ID numérico. Retorna 204 em caso de sucesso. Ver referência.

[2026-06-11]

Added

Endpoint de atualização de nome de categoria (PATCH /categories/v1/categories/{id}): renomeia uma categoria customizada existente; apenas o campo name é atualizado — os estabelecimentos vinculados e o tipo da categoria permanecem inalterados. O novo nome deve ser único na empresa. Ver referência.
Endpoint de exclusão de categorias (DELETE /categories/v1/categories): deleta uma ou mais categorias customizadas em uma única requisição. Se a categoria tiver estabelecimentos vinculados, informe moveTo para reatribuí-los antes da exclusão — omitir retorna 422. Ver referência.

[2026-06-03]

Added

Endpoint de atualização parcial de usuário (PATCH /users/v1/users/{userId}): atualiza name e/ou roleId de um usuário ativo da empresa; ao menos um campo obrigatório por requisição. Ver referência.
Adiciona endpoint de listagem de fornecedores (GET /suppliers/v1/suppliers). Ver referência.
Adiciona endpoint de consulta de fornecedor por ID (GET /suppliers/v1/suppliers/{id}). Ver referência.
Adiciona endpoint de criação de fornecedor (POST /suppliers/v1/suppliers). Ver referência.

[2026-05-28]

Added

Endpoint de listagem de centros de custo (GET /cost-centers/v1/cost-centers): lista todos os centros de custo da empresa autenticada. A resposta inclui id, name, companyId e o campo opcional responsible com nome e ID do responsável vinculado. Ver referência.

Changed

Endpoint PATCH /statements/v1/credit-card/{transactionId}: adicionado campo costCenterId (UUID) para classificar a transação por centro de custo. Ver referência.

[2026-05-27]

Added

Endpoint de consulta de usuário por ID (GET /users/v1/users/{userId}): retorna os dados de um usuário específico da empresa pelo identificador (UUID v4); resposta alinhada ao item da listagem (UserDto), com 404 quando o usuário não pertencer à empresa autenticada.

[2026-05-26]

Added

Endpoint de atualização de transação de cartão (PATCH /statements/v1/credit-card/{transactionId}): atualiza notes, isConciled e categoryId de uma transação de cartão de crédito; ao menos um campo obrigatório por requisição.

[2026-05-14]

Changed

Endpoint de extrato de cartão (GET /statements/v1/credit-card): adicionado parâmetro opcional cardIds (string, separado por vírgula) para filtrar transações por um ou mais cartões simultaneamente.

[2026-04-28]

Added

Endpoint de criação de categoria (POST /categories/v1/categories): cria uma categoria personalizada para a empresa; o nome deve ser único entre as categorias da empresa.
Endpoint de consulta de categoria por ID (GET /categories/v1/categories/{id}): retorna uma categoria da empresa pelo identificador numérico; resposta alinhada ao item da listagem (estabelecimentos e tipo).

[2026-04-17]

Added

Endpoint de listagem de categorias (GET /categories/v1/categories): retorna as categorias disponíveis para a empresa.

[2026-04-10]

Added

Endpoint de extrato bancário (GET /statements/v1/banking): consulta paginada de transações bancárias da empresa com suporte a filtros por período, conta, categoria, centro de custo, status, valor e responsável.

[2026-04-02]

Changed

Resposta do extrato de cartão (GET /statements/v1/credit-card): cada anexo em attachments pode incluir o campo opcional type com o MIME (image/jpeg, image/png ou application/pdf) quando a extensão do nome do arquivo for reconhecida.

[2026-03-27]

Added

Endpoint de exclusão de usuários (DELETE /users/v1/users/{userId}): permite remover um usuário da empresa pelo ID.

[2026-03-25]

Added

Endpoint de criação de convites de usuários (POST /users/v1/invites): permite enviar convites para novos usuários se juntarem à empresa, informando e-mail e papel (role).

[2026-03-24]

Added

Endpoint de listagem de papéis (roles) (/users/v1/roles): retorna os papéis da empresa com perfil, permissões (claims) e quantidade de usuários vinculados.

[2026-03-23]

Added

Endpoint de listagem de convites de usuários (/users/v1/invites): consulta paginada de convites com filtros por status e papel (role).

[2026-03-17]

Changed

Endpoint de extrato de cartão (/statements/v1/credit-card): documentação atualizada de POST para GET, com parâmetros de filtro (limit, startDate, endDate, types, nextPageStartKey) enviados via query string.

[2026-03-16]

Added

Endpoints de gestão de cartões corporativos: listagem com filtros, bloqueio e desbloqueio de cartões.
Endpoint de listagem de usuários da empresa, com filtro por e-mail e paginação por cursor.

[2026-02-25]

Added

Endpoint de listagem de cartões de crédito.

[2026-02-09]

Added

Endpoint de login para autenticação na API Conta Simples.

[2026-02-03]

Added

Endpoint para download de anexos de transações.

[2026-01-19]

Added

Incremento no endpoint de extrato de cartão, incluindo novos campos relacionados a anexos.

[2025-10-15]

Added

Endpoint de extrato de cartão.
Definição inicial do schema da API para transações e cartões.

Was this page helpful?