Changelog

Versão da API

A versão atual é a v1, no caminho /api/integration/v1. Esta página registra as mudanças da API e da documentação.

Política de versões

Dentro da v1, só entram mudanças compatíveis. Elas são publicadas sem aviso prévio e registradas no histórico abaixo:

• endpoint novo;
• campo opcional novo no corpo da requisição;
• campo novo na resposta ou no data de um evento;
• tipo de evento novo (você só recebe os eventos que assinou);
• valor novo de status, stage ou code de erro para uma situação que antes não existia.

Mudança incompatível vai para uma versão nova do caminho (/api/integration/v2). Contam como incompatíveis:

• remover ou renomear um campo;
• mudar o tipo de um campo;
• tornar obrigatório um campo que era opcional;
• mudar o significado de um status HTTP ou de um code de erro;
• deixar de emitir um tipo de evento.

Histórico

1. 16/10/2026 API

   Arquivo de outra nota é recusado

   • POST /pre-authorizations responde 422 PRE_AUTH_INVOICE_FILE_MISMATCH quando o arquivo anexado traz a chave de acesso de outra nota (o número da chave não é o invoice.number informado).
   • O número lido do arquivo vem em details[0].fileInvoiceNumber. Zeros à esquerda e sufixo de parcela continuam aceitos.
   • Arquivo sem chave legível continua aceito.
2. 01/10/2026 Webhooks

   O boleto no evento de emissão

   • anticipation.billed e anticipation.extension_concluded passam a trazer, para a construtora, o objeto bill: linha digitável, código de barras, vencimento, nosso número, valor e a URL do PDF.
   • Novo endpoint GET /anticipations/{id}/bill-file devolve o PDF do boleto, com o escopo preauth:read.
   • O fornecedor continua recebendo esses eventos sem o objeto bill.
3. 15/09/2026 API

   Consulta, cancelamento idempotente e nota duplicada

   • Novos endpoints GET /pre-authorizations/{id} e GET /pre-authorizations (filtros externalReference e status), com o escopo preauth:read.
   • Cancelar de novo uma pré-autorização que a integração já cancelou responde 201 com o estado atual, sem novo evento.
   • O 422 do cancelamento passa a separar PRE_AUTH_ALREADY_REQUESTED (o fornecedor já solicitou) de PRE_AUTH_ALREADY_CLOSED (encerrada por outro motivo).
   • Criar uma segunda operação em andamento para a mesma nota do mesmo fornecedor responde 409 PRE_AUTH_DUPLICATE_INVOICE, com o id existente em details.
   • O escopo notes:read deixou de ser oferecido para chaves novas; chaves antigas continuam válidas. A validade da chave passa a ser escolhida na criação.
4. 15/09/2026 Webhooks

   Eventos novos e emissão garantida

   • Novos tipos: anticipation.reopened (operação reprovada reaberta para análise) e anticipation.payout_returned (pagamento ao fornecedor devolvido pelo banco).
   • anticipation.reproved passa a ser enviado também quando a operação da Oneos reprova a solicitação.
   • payment_order.created passa a ser enviado quando a ordem de pagamento é gerada.
   • O aviso é gravado na mesma operação que muda o status: se a mudança aconteceu, o evento existe.
5. 15/09/2026 Documentação

   Nova documentação em docs.oneos.com.br

   • Referência dos campos e OpenAPI 3.1 gerados dos contratos da plataforma.
   • Idempotência, limites de requisição, envio do arquivo da nota e catálogo completo de eventos documentados.
   • Verificador de assinatura de webhook no navegador.