Todas as mudancas notaveis deste projeto serao documentadas neste arquivo.
O formato e baseado em Keep a Changelog, e este projeto adere ao Versionamento Semantico.
Ajustes para o fluxo de criação de subcontas via API e suporte a testes contra mocks locais. Todas as mudanças são aditivas (não-breaking): novos campos opcionais e um parâmetro de construtor opcional com default.
AsaasAccount (criação de subconta):
CreateAccountRequest.IncomeValue(decimal?) — faturamento/renda mensal em BRL. Obrigatório no Asaas desde 2024 para criar subcontas.CreateAccountRequest.BirthDate(string, formatoyyyy-MM-dd) — data de nascimento do titular. Obrigatório para pessoa física; omitir para PJ.
Infraestrutura:
ApiSettings.BaseUrl(string, opcional) — override da URL base. Quando informado, sobrepõe o ambiente (AsaasEnvironment) e é usado emBaseManager.BuildBaseAddress(). Uso típico: apontar para um mock local (ex.: Mockoon) em testes. Novo parâmetro opcionalbaseUrl = nullno construtor deApiSettings(compatível com o uso existente).
Segunda rodada da auditoria, agora cobrindo os 16 managers restantes que tinham ficado de fora da v3.1.0: Customer, Payment (resto), Subscription, Pix, Transfer, Anticipation, Installment, Webhook, Wallet, Notification, CreditCard, PaymentLink, Finance, MyAccount (resto), AsaasAccount, FiscalInfo, Chargeback, Sandbox.
Veja CONFORMANCE.md §12–§29 para o relatório endpoint-a-endpoint e §50 para o consolidado de padrões de bug por categoria.
Pix (CRÍTICO):
PixTransactionStatusenum tinha 5 valores INVENTADOS (PENDING, DONE, CANCELLED, SCHEDULED, FAILED). Schema real: 11 valores. PENDING e FAILED não existem. Sem o fix, deserializar JSON real do sandbox lançava exception em qualquer transacao em estado de espera (AWAITING_*, REQUESTED, REFUSED).PixTransactionreescrito (7 → 25 campos). Renomeados:TransactionDate→EffectiveDate,ScheduleDate→ScheduledDate.PixAddressKey.Statusstring → enumPixAddressKeyStatus(6 valores). Adicionados QrCode (nested), CanBeDeleted, CannotBeDeletedReason.- Novos enums:
PixTransactionType(5),PixTransactionOriginType(6),PixTransactionFinality(2),PixAddressKeyStatus(6). - Novo filtro:
PixTransactionListFilter(status, type, endToEndIdentifier).
Customer:
Customer.DateCreated→ DateTime?Create/UpdateCustomerRequest.NotificationDisabled→ bool? (antes forçava false em todo update parcial).- Novo:
CustomerManager.GetNotifications(customerId)(endpoint estava faltando).
Payment:
Payment.DateCreated,DueDate,OriginalDueDate→ DateTime?PaymentListFilter: 9 filtros novos (customerGroupName, invoiceStatus, estimatedCreditDate, pixQrCodeId, anticipable, user, checkoutSession, dateCreated[ge]/[le], estimatedCreditDate[ge]/[le]).
Subscription:
SubscriptionStatusenum: adicionadoINACTIVE(3 valores).Subscription.DateCreated,NextDueDate→ DateTime?- Adicionados: Object, PaymentLinkId, CheckoutSession, Split (array).
SubscriptionListFilter: 6 campos novos (customerGroupName, status enum, deletedOnly, externalReference, order, sort).
Transfer:
AsaasAccountTransferStatusenum: 3 → 5 valores (adicionados BANK_PROCESSING, FAILED).BaseTransfer.DateCreated→ DateTime?,Authorized→ bool?- Novo enum:
TransferOperationType(PIX/TED/INTERNAL). BaseTransferadicionados: Object, NetValue (movido), EndToEndIdentifier, FailReason, ExternalReference, Description, Recurring.TransferListFilter: dateCreated[ge]/[le], transferDate[ge]/[le].Bankmodel: adicionados Ispb + Name.BankAccount: adicionados AgencyDigit, PixAddressKey, Ispb.
Anticipation:
Anticipation.AnticipationDate,DueDate,RequestDate→ DateTime?, +Object.
Installment:
Installment.ExpirationDay→ int?- Adicionados: CreditCard (nested), Refunds (array de InstallmentRefund).
Notification:
- Novo enum
NotificationEvent(6 valores). Antes não existia. - Notification + UpdateNotificationRequest: todos os 7 bools → bool?
- Notification adicionados: Object, Event (enum), Deleted.
CreditCard:
Common.CreditCard.Brandstring → enumCreditCardBrand(13 valores).PreAuthorizationConfigreescrito: tinha {Enabled, AutomaticCaptureDelay} INVENTADOS. Schema: {DaysToExpire}. IdemSavePreAuthorizationConfigRequest.
PaymentLink:
PaymentLink.SubscriptionCyclestring →Cycleenum (7 valores).- Adicionados: ViewCount, IsAddressRequired, ExternalReference.
- Value, Active, NotificationEnabled, Deleted, DueDateLimitDays, MaxInstallmentCount → nullable.
Finance:
SplitStatisticsreescrito: tinha {TotalPendingValue, TotalReceivedValue} INVENTADOS. Schema: {income, value}.- Novo filter:
PaymentStatisticsFilter(11 campos). GetPaymentStatistics agora aceita filtros opcionais.
MyAccount:
MyAccount.Statusstring → enumAccountInfoStatus(4 valores).- Adicionados: CompanyName, IncomeValue, TradingName, Site, AvailableCompanyNames (array), CommercialInfoExpiration (nested).
InscricaoEstadualmarcado [Obsolete] (não existe no schema).
AsaasAccount:
Account.Citystring → long? (schema: integer city id).- Adicionados: Object, Id, BirthDate, TradingName, Site, AccountNumber (nested), CommercialInfoExpiration (nested).
ApiKeymarcado [Obsolete] (não existe no schema).
FiscalInfo:
RpsNumber,LoteNumberstring → int? (schema: integer).- Adicionados: NbsCode, PasswordSent, AccessTokenSent, CertificateSent, NationalPortalTaxCalculationRegime, Object.
StateInscription,AccessTokenmarcados [Obsolete] (não existem no schema).- SimplesNacional, CulturalProjectsPromoter → bool?
Chargeback:
- Adicionado
ChargebackCreditCard(nested: number + brand enum). Reason→ nullable.
Wallet:
- Adicionado: Object.
- 16 novos enums tipados (PixTransactionStatus, PixTransactionType, PixTransactionOriginType, PixTransactionFinality, PixAddressKeyStatus, SubscriptionStatus expandido, NotificationEvent, CreditCardBrand, TransferOperationType, AsaasAccountTransferStatus expandido, AccountInfoStatus, BillPaymentStatus expandido em fase anterior, etc).
- Novos models: PixTransactionExternalAccount, PixOriginalTransaction, PixTransactionQrCode, PixAddressKeyQrCode, PixTransactionListFilter, ChargebackCreditCard, CommercialInfoExpiration, AccountNumber (já existia), InstallmentRefund, PaymentStatisticsFilter.
- 10 novos integration tests cobrindo Subscription, Pix, Transfer, Anticipation, Finance (15 tests no total).
- CI workflow
integration-sandbox.yml: workflow_dispatch (manual) + nightly schedule, com secret ASAAS_SANDBOX_TOKEN. - CI workflow
ci.ymlatualizado para filtrarCategory!=Integration(não quebra sem token). - CONFORMANCE.md §12–§29 (16 novos managers), §50 (cross-pattern bug list).
- 18 famílias de bugs (B-25 a B-42). Veja CONFORMANCE.md §50 para consolidação por padrão.
- Testes: 599 → 664 unit/contract (+65) + 15 integration skip-by-default.
- Managers auditados: 11 → 27 (100%).
- Bugs cumulativos: 24 → 42 famílias (B-19 a B-42).
- Build warnings: 0.
Rodada final de conformidade contra o MCP oficial Asaas. Para cada manager auditado, modelos foram verificados campo-a-campo contra OpenAPI, fixtures criadas a partir dos exemplos oficiais e contract tests congelam o shape JSON. Veja CONFORMANCE.md para o relatorio completo endpoint-a-endpoint.
PaymentDunning:
DunningNumber: string->int?(era chute; schema integer).Status: bool->bool?emCanBeCancelledeIsNecessaryResendDocumentation(schema permite null; valor false silencioso antes do fix).PaymentDunningEventHistory.Status: string-> enumPaymentDunningHistoryStatus.SimulatedPaymentDunning.TypeSimulationsePaymentDunningPaymentAvailable.TypeSimulations: objeto unico ->List<PaymentDunningTypeSimulations>(schema sempre foi array — antes lancavaInvalidCastExceptionno JSON real).Simulate(request)agora enviapaymentcomo QUERY param (schema), nao body.ReceivedInCashFeeValueeCancellationFeeValuemarcados[Obsolete].- Adicionados:
CannotBeCancelledReason, valor enumDEBT_RECOVERY_ASSISTANCE(emPaymentDunningType, aceito pelo filter).
CreditBureauReport:
CreditBureauReport.StateeStatusREMOVIDOS (nao existem no schema).CreateCreditBureauReportRequest.StateREMOVIDO.- Adicionados:
DownloadUrl,ReportFile(PDF Base64 — apenas em response do POST). - Novo:
CreditBureauReportListFiltercomStartDate/EndDate. OverloadList(offset, limit, filter)backwards-compatible.
BillPayment:
BillPayment: adicionadosInterest,Fine,PaymentDate,ExternalReference.FailReasons: string->List<string>(schema array).CanBeCancelled/DueDate/ScheduleDate/PaymentDate-> nullable.BillPaymentStatusenum: adicionadosREFUNDEDeAWAITING_CHECKOUT_RISK_ANALYSIS_REQUEST(5 -> 7 valores).CreateBillPaymentRequest: adicionadosInterest,Fine,ExternalReference.Value/DueDate/ScheduleDate/Discount-> nullable.BankSlipInfo: 5 campos comBankCode(chute) -> 17 campos comBank,Beneficiary*,Min/MaxValue,AllowChangeValue,Discount/Interest/FineValue,OriginalValue,TotalDiscount/AdditionalValue,IsOverdue.
Invoice:
Taxes: 7 campos -> 19 (NBS code, situacao tributaria, classificacao, operacao, PIS/COFINS retention type/status + 6 campos da Reforma Tributaria:StateIbs,StateIbsValue,MunicipalIbs,MunicipalIbsValue,Cbs,CbsValue).InvoiceListFilter:effectiveDate[ge]/[le]->[Ge]/[Le](G/L MAIUSCULOS, schema oficial). Casing errado era silenciosamente ignorado pela API. Adicionados filtroscustomereexternalReference.CreateInvoiceRequesteUpdateInvoiceRequest: adicionadoUpdatePayment: bool?.
AccountDocument (subgrupo MyAccount):
AccountDocumentFileREMOVIDO (Name/Url eram inventados; schema retorna apenas{id, status}).SubmitDocument,ViewDocumentFile,UpdateDocumentFileagora retornamAccountDocument(antes retornavam tipo errado).- 4 enums tipados criados:
AccountDocumentStatus(4),AccountDocumentGroupStatus(5, ganha IGNORED),AccountDocumentType(12),AccountDocumentResponsibleType(13). Status/Type eramstring/List<string>antes. UploadAccountDocumentRequest:DocumentType: string->Type: AccountDocumentType?,File: IAsaasFile->DocumentFile: IAsaasFile(alinhando com nomes multipart "type" e "documentFile" do schema).
MobilePhoneRecharge:
MobilePhoneProvider.AvailableValues: List<decimal>(chute) ->Values: List<MobilePhoneProviderValue>com{Name, Description, Bonus, MinValue, MaxValue}conforme schema.
PixAutomatic (B-16/B-17 do REVIEW pre-existente):
PixAutomaticPaymentInstruction.Authorizationvirou objeto aninhado comId/EndToEndIdentifier/CustomerId. AdicionadosDueDate,EndToEndIdentifier,PaymentId,RefusalReason.Statusvirou enumPixAutomaticPaymentInstructionStatus(5 valores).PixAutomaticPaymentInstructionListFilter: camposauthorization/status->authorizationId/customerId/paymentId/status(typed).
- CONFORMANCE.md — relatorio endpoint-a-endpoint da auditoria com tabelas por manager, bugs (B-XX) corrigidos, fixtures, contract tests.
- Integration tests sandbox (
Codout.Apis.Asaas.Tests/Integration/): 5 testes reais contraapi-sandbox.asaas.com, skip automatico via[IntegrationFact]quandoASAAS_SANDBOX_TOKENausente. - Contract tests (
Codout.Apis.Asaas.Tests/Contract/): 95+ novos testes que congelam o shape JSON de request/response com fixtures dos exemplos MCP. PixRecurringTransactionListFilter(status/value/searchText) — feature anteriormente nao exposta.- Bug pre-existente fixado em paralelo:
Subscription.Enums.Cycle.BIMONTHLY(estava faltando, presente em schemas de Subscription e Checkout).
RequestParameters.Add(decimal?)agora usaCultureInfo.InvariantCulture(pt-BR estava gerando12,5em vez de12.5).RequestParameters.Add(bool?)serializatrue/falselowercase (antesTrue/False— Asaas ignorava silenciosamente).DateTimeExtensions.ToApiRequestdefensivamente forcaInvariantCulture.
Major release com auditoria completa de conformidade contra a documentacao
oficial do Asaas (via MCP https://docs.asaas.com/mcp). Veja AUDIT.md,
IMPLEMENTATION_PLAN.md e REVIEW.md para o relatorio detalhado.
asaas.ReceivableAnticipationrenomeado paraasaas.Anticipation(alinhar com o naming dos demais 26 managers que usam nome curto). Migracao:asaas.ReceivableAnticipation.X->asaas.Anticipation.X.ReceivableAnticipationStatusExtensionrenomeado paraAnticipationStatusExtension.AccountStatus.{CommercialInfo,Documentation,General,BankAccountInfo}passaram destringpara enumAccountApprovalStatus(PENDING/APPROVED/REJECTED/AWAITING_APPROVAL).BaseManager._settingspassou deprivateparaprotected Settings(convencao PascalCase de protected field). Codigo que herdava deBaseManagere usava_settingsprecisa migrar paraSettings.
Cobertura do SDK passou de ~45% (70 endpoints) para 100% (~156 endpoints documentados). Suite de testes passou de 400 para ~500 testes.
HTTP method:
CustomerManager.Update,PaymentManager.Update,SubscriptionManager.Update,SubscriptionManager.UpdateInvoiceSettings,NotificationManager.Update,NotificationManager.BatchUpdateagora enviam PUT (antes era POST, sem efeito).
Renomeacoes / mudancas de rota:
CustomerFiscalInfoManager->FiscalInfoManager; classes renomeadas (CustomerFiscalInfo->FiscalInfo,CreateCustomerFiscalInfoRequest->CreateFiscalInfoRequest). Rota corrigida:/v3/customerFiscalInfo->/v3/fiscalInfo. Acesso facade:asaas.CustomerFiscalInfo->asaas.FiscalInfo.InvoiceManager.ListMunicipalServicesremovido e movido paraFiscalInfoManager.ListServices(rota correta/v3/fiscalInfo/services).FinanceManager.Balance()(retornandodecimal) renomeado paraGetBalance()retornandoResponseObject<Balance>(a API retorna objeto).MyAccountManager.Find()removido (apontava para rota errada). Substituido porGetCommercialInfo()(rota/v3/myAccount/commercialInfo).TransferManager.Execute(...)removido (overload ambiguo). Substituido porTransferToBankAccount(...)(POST/v3/transfers) eTransferToAsaasAccount(...)(POST/v3/transfers/, com barra final = endpoint separado).WebhookManagertotalmente reescrito de "webhook unico por tipo" (rotas/v3/webhook,/v3/webhook/invoice,/v3/webhook/mobilePhoneRechargeque ja nao existem) para CRUD por id em/v3/webhooks/{id}. Veja secao de migracao no final.MunicipalService.Issrenomeado paraIssTax(nome correto na API).
Remocoes:
AnticipationManager.SignAgreementeSignAnticipationAgreementRequestremovidos: o endpoint/v3/anticipations/agreement/signnao existe na API.
Modelos:
Customer.Deleted,Customer.NotificationDisabled,Payment.Deleted,Payment.PostalService,Payment.Anticipatedconvertidos parabool?.WebhookRequestremovido (substituido porCreateWebhookRequest/UpdateWebhookRequest).
- 7 bugs bloqueantes que faziam chamadas reais falharem (PUT->POST, rotas incorretas, shape de resposta errado, endpoint inexistente, manager sem metodo de criacao).
- Sockets esgotando em apps de alto trafego:
SocketsHttpHandleragora e compartilhado entre todas as instancias de manager.
- ChargebackManager - 3 endpoints (
/v3/chargebacks/*) - EscrowManager - 6 endpoints (Conta de Garantia)
- CheckoutManager - 2 endpoints (
/v3/checkouts/*) - MobilePhoneRechargeManager - 5 endpoints (
/v3/mobilePhoneRecharges/*) - SandboxManager - 3 helpers de teste (
/v3/sandbox/*, lanca excecao em producao) - PixAutomaticManager - 6 endpoints (
/v3/pix/automatic/*) - PixRecurringManager - 5 endpoints (
/v3/pix/transactions/recurrings/*)
- PaymentManager (+18 endpoints): documentos (5), simulate, limits, billingInfo, viewingInfo, status, refunds, bankSlip/refund, captureAuthorizedPayment, payWithCreditCard, createWithCreditCard, splits queries paid/received (4).
- SubscriptionManager (+1): UpdateCreditCard.
- InstallmentManager (+5): Create, CreateWithCreditCard, ListPayments, CancelPendingPayments, UpdateSplits.
- PixManager (+3): FindTransaction, DeleteStaticQrCode, GetAddressKeyTokenBucket.
- AnticipationManager (+4): Cancel, GetLimits, GetAutomaticConfiguration, UpdateAutomaticConfiguration.
- CreditCardManager (+2): SavePreAuthorizationConfig, GetPreAuthorizationConfig.
- TransferManager (+1): Cancel.
- MyAccountManager (+8): GetCommercialInfo, UpdateCommercialInfo, GetStatus, DeleteWhiteLabelAccount, ListPendingDocuments, SubmitDocument, ViewDocumentFile, UpdateDocumentFile, DeleteDocumentFile.
- AsaasAccountManager (+6): Find, ResendActivationLink, CreateAccessToken, ListAccessTokens, UpdateAccessToken, DeleteAccessToken.
- FiscalInfoManager (+1): ListServices.
Customer: Object, CityName, StateInscription, Company, GroupName, ForeignCustomer.Payment: Object, PixTransaction, PixQrCodeId, CheckoutSession, PaymentLinkId, InstallmentNumber, CreditDate, EstimatedCreditDate, TransactionReceiptUrl, NossoNumero, Anticipable, CanBePaidAfterDueDate, DaysAfterDueDateToRegistrationCancellation.CreatePaymentRequest: Callback, PixAutomaticAuthorizationId, DaysAfterDueDateToRegistrationCancellation.PaymentStatus: valor REFUND_IN_PROGRESS.CreateCustomerRequest/UpdateCustomerRequest: Company, ForeignCustomer (e GroupName no Update).- Enums
WebhookEvent(~100 valores) eWebhookSendType. - Enums
ChargebackStatus,ChargebackReason(32 valores),ChargebackDisputeStatus.
BaseResponse.WasSucessfull()corrigido paraWasSuccessful(). Versao com typo mantida como[Obsolete]alias temporario.BaseManageragora usaSocketsHttpHandlerestatico compartilhado entre todas as instancias para nao esgotar sockets em apps de alto trafego.
// PUT agora e usado automaticamente nos Updates - nenhuma mudanca de codigo necessaria
await asaas.Customer.Update("cus_123", req); // antes: POST, agora: PUT
// FiscalInfo
asaas.CustomerFiscalInfo.X -> asaas.FiscalInfo.X
new CustomerFiscalInfo() -> new FiscalInfo()
new CreateCustomerFiscalInfoRequest() -> new CreateFiscalInfoRequest()
// Invoice.ListMunicipalServices movido para FiscalInfo.ListServices
await asaas.Invoice.ListMunicipalServices("IT");
// agora:
await asaas.FiscalInfo.ListServices("IT");
// Finance balance shape mudou
decimal saldo = (await asaas.Finance.Balance()).Data;
// agora:
decimal saldo = (await asaas.Finance.GetBalance()).Data.Value;
// Transfer
await asaas.Transfer.Execute(asaasRequest); // ambiguo
// agora:
await asaas.Transfer.TransferToAsaasAccount(asaasRequest);
await asaas.Transfer.TransferToBankAccount(bankRequest);
// MyAccount.Find -> GetCommercialInfo
var info = (await asaas.MyAccount.Find()).Data;
// agora:
var info = (await asaas.MyAccount.GetCommercialInfo()).Data;
// Webhook completamente novo
// Antes (nao funcionava mais em nenhuma versao da API):
await asaas.Webhook.CreateOrUpdatePaymentWebhook(new WebhookRequest { ... });
// Agora:
await asaas.Webhook.Create(new CreateWebhookRequest
{
Name = "Meu webhook",
Url = "https://example.com/hook",
Email = "ops@example.com",
Enabled = true,
ApiVersion = 3,
AuthToken = "whsec_min32chars......",
SendType = WebhookSendType.SEQUENTIALLY,
Events = [WebhookEvent.PAYMENT_CONFIRMED, WebhookEvent.PAYMENT_RECEIVED]
});
// AnticipationManager.SignAgreement removido - se voce usava esse metodo,
// agora o termo de antecipacao e assinado direto no painel web do Asaas.- CreditCardToken em
CreateSubscriptionRequest: agora e possivel criar uma assinatura recorrente reutilizando um token de cartao previamente gerado porTokenizeCreditCard, sem precisar enviar novamente os dados sensiveis (numero/CCV). Paridade comCreatePaymentRequest, que ja expunha esta propriedade.
- DateTime deserialization: Criado
FlexibleDateTimeConverterque aceita tanto formato date-only (yyyy-MM-dd) quanto ISO 8601 completo (yyyy-MM-ddTHH:mm:ssZ), resolvendoJsonExceptionem campos comoexpirationDateretornados pela API Asaas. - Abstract type deserialization: Removido
abstractdeBaseDeletedeBaseTransfer, permitindo queSystem.Text.Jsondesserialize respostas de operacoes DELETE e listagem de transferencias. - Enum deserialization: Substituido
JsonStringEnumConverterpeloSafeEnumConverterFactoryque retorna o valor default em vez de lancarJsonExceptionquando a API retorna um valor de enum nao mapeado no SDK. - NullReferenceException em listas: Todas as propriedades
List<T>nos models agora sao inicializadas com listas vazias, evitandoNullReferenceExceptionao iterar respostas da API.
ExternalReferencenos modelsInvoice,CreateInvoiceRequesteUpdateInvoiceRequest.WhatsappEnabledForCustomerno modelUpdateNotificationRequest.
- Novos modulos:
PaymentLinkManager,PixManager,NotificationManager,CreditBureauReportManager,CustomerFiscalInfoManager. - Novos endpoints em managers existentes:
UndoReceivedInCash,ListPaymentBook,ListPayments,Find(transfer),SignAgreement,PaymentStatistics,SplitStatistics,FindAccountNumber, webhooks paraMobilePhoneRecharge. - Suporte a
PUTviaPutAsync<T>noBaseManager. - 400 testes unitarios com xUnit + Moq.
- README completo com exemplos de uso.
- Configuracao de pacote NuGet com SourceLink e symbol packages (.snupkg).
- Breaking: Migrado de
Newtonsoft.JsonparaSystem.Text.Json(zero dependencias externas). - Corrigido path de
Balancepara/finance/balance. Invoice Updateagora usaPUTcorretamente em vez dePOST.BuildHttpClient()agora eprotected virtualpara permitir mocking em testes.
- Release inicial do SDK.
- Managers: Customer, Payment, Subscription, Installment, Finance, Transfer, Wallet, Webhook, AsaasAccount, Anticipation, MyAccount, Invoice, PaymentDunning, BillPayment, CreditCard.
- Suporte a ambientes Production e Sandbox.
- Serializacao com Newtonsoft.Json.