Audit/asaas api conformance

.github/workflows/ci.yml

@@ -28,5 +28,5 @@ jobs:
       - name: Build library
         run: dotnet build Codout.Apis.Asaas/Codout.Apis.Asaas.csproj --configuration Release --no-restore
 
-      - name: Test
-        run: dotnet test Codout.Apis.Asaas.Tests/Codout.Apis.Asaas.Tests.csproj --configuration Release --logger "console;verbosity=normal"
+      - name: Test (unit + contract — integration are auto-skipped without ASAAS_SANDBOX_TOKEN)
+        run: dotnet test Codout.Apis.Asaas.Tests/Codout.Apis.Asaas.Tests.csproj --configuration Release --logger "console;verbosity=normal" --filter "Category!=Integration"

.github/workflows/integration-sandbox.yml

@@ -0,0 +1,51 @@
+name: Integration (sandbox)
+
+# Roda os integration tests reais contra api-sandbox.asaas.com.
+# Requer secret ASAAS_SANDBOX_TOKEN configurado no repositorio
+# (Settings -> Secrets and variables -> Actions).
+#
+# Triggers:
+#   - manual (workflow_dispatch): permite rodar sob demanda
+#   - schedule (nightly): valida o SDK contra mudancas no sandbox
+#
+# Nao bloqueia PRs comuns (rodar em job separado).
+
+on:
+  workflow_dispatch:
+  schedule:
+    # Diariamente as 04:00 UTC (01:00 BRT)
+    - cron: '0 4 * * *'
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '10.0.x'
+
+      - name: Restore library
+        run: dotnet restore Codout.Apis.Asaas/Codout.Apis.Asaas.csproj
+
+      - name: Restore tests
+        run: dotnet restore Codout.Apis.Asaas.Tests/Codout.Apis.Asaas.Tests.csproj
+
+      - name: Build library
+        run: dotnet build Codout.Apis.Asaas/Codout.Apis.Asaas.csproj --configuration Release --no-restore
+
+      - name: Integration tests (sandbox)
+        env:
+          ASAAS_SANDBOX_TOKEN: ${{ secrets.ASAAS_SANDBOX_TOKEN }}
+        run: |
+          if [ -z "$ASAAS_SANDBOX_TOKEN" ]; then
+            echo "::warning::ASAAS_SANDBOX_TOKEN secret nao configurado. Integration tests serao todos skipados."
+          fi
+          dotnet test Codout.Apis.Asaas.Tests/Codout.Apis.Asaas.Tests.csproj \
+            --configuration Release \
+            --logger "console;verbosity=normal" \
+            --filter "Category=Integration"

.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "asaas": {
+      "type": "http",
+      "url": "https://docs.asaas.com/mcp"
+    }
+  }
+}

Codout.Apis.Asaas.Sample/Program.cs

@@ -11,7 +11,7 @@
 
 ResponseObject<Customer> customerResponse = await asaasApi.Customer.Find("cus_13bFHumeyglN");
 
-if (customerResponse.WasSucessfull())
+if (customerResponse.WasSuccessful())
 {
     Customer customer = customerResponse.Data;
 

Codout.Apis.Asaas.Tests/Codout.Apis.Asaas.Tests.csproj

@@ -23,4 +23,12 @@
     <ProjectReference Include="..\Codout.Apis.Asaas\Codout.Apis.Asaas.csproj" />
   </ItemGroup>
 
+  <ItemGroup>
+    <!-- Fixtures JSON extraidas da documentacao oficial Asaas; copiadas para o
+         diretorio de saida para serem lidas pelos contract tests em runtime. -->
+    <None Update="Fixtures\**\*.json">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
+  </ItemGroup>
+
 </Project>

Codout.Apis.Asaas.Tests/Contract/AccountDocumentContractTests.cs

@@ -0,0 +1,183 @@
+using System;
+using System.Text.Json;
+using Codout.Apis.Asaas.Models.MyAccount;
+using Codout.Apis.Asaas.Models.MyAccount.Enums;
+
+namespace Codout.Apis.Asaas.Tests.Contract;
+
+/// <summary>
+/// Contract tests para os endpoints de Account Document (MyAccountManager).
+/// Schemas verificados via MCP em 2026-05-24:
+/// - GET /v3/myAccount/documents (envelope {data:[...]} sem paginacao + rejectReasons)
+/// - POST /v3/myAccount/documents/{id} (multipart, retorna AccountDocument {id,status})
+/// - GET /v3/myAccount/documents/files/{id} (retorna AccountDocument {id,status})
+/// - POST /v3/myAccount/documents/files/{id} (multipart, retorna AccountDocument)
+/// - DELETE /v3/myAccount/documents/files/{id} ({deleted, id})
+/// </summary>
+public class AccountDocumentContractTests
+{
+    // ─────────────────────────────────────────────────────────────
+    // GET /v3/myAccount/documents -> AccountDocumentShowResponseDTO
+    // Envelope minimalista: { rejectReasons, data: [...] } (sem paginacao!)
+    // ─────────────────────────────────────────────────────────────
+
+    [Fact]
+    public void PendingDocumentsResponse_DeserializesFromOfficialFixture()
+    {
+        var json = FixtureLoader.Load("AccountDocument/pending-documents-response.json");
+
+        var result = JsonContractAssert.DeserializeFixture<AccountDocumentResponse>(json);
+
+        Assert.Null(result.RejectReasons);
+        Assert.Single(result.Data);
+
+        var group = result.Data[0];
+        Assert.Equal("172ed152-4fa4-43ad-9b69-39c323e9526c", group.Id);
+        Assert.Equal(AccountDocumentGroupStatus.NOT_SENT, group.Status);
+        Assert.Equal(AccountDocumentType.MINUTES_OF_CONSTITUTION, group.Type);
+        Assert.Equal("Minutes of election of the last board", group.Title);
+        Assert.Equal("No description", group.Description);
+        Assert.Equal("https://example.com/cadastro.io/8ad196d6cbfcc5d05bfabcbb5c730f6a", group.OnboardingUrl);
+        Assert.Equal(new DateTime(2025, 3, 4), group.OnboardingUrlExpirationDate);
+
+        Assert.NotNull(group.Responsible);
+        Assert.Equal("John Doe", group.Responsible.Name);
+        Assert.Single(group.Responsible.Type);
+        Assert.Equal(AccountDocumentResponsibleType.ASSOCIATION, group.Responsible.Type[0]);
+
+        Assert.Single(group.Documents);
+        Assert.Equal("8d257732-2220-11ec-b695-b6af4a64184d", group.Documents[0].Id);
+        Assert.Equal(AccountDocumentStatus.PENDING, group.Documents[0].Status);
+    }
+
+    [Fact]
+    public void PendingDocumentsResponse_UsesMinimalEnvelopeWithoutPagination()
+    {
+        // B-07 regression: o envelope tem APENAS {rejectReasons, data},
+        // sem hasMore/totalCount/limit/offset. Usar ResponseList aqui
+        // resultaria em propriedades vazias.
+        var json = FixtureLoader.Load("AccountDocument/pending-documents-response.json");
+
+        JsonContractAssert.HasRootProperty(json, "data", JsonValueKind.Array);
+        JsonContractAssert.HasRootProperty(json, "rejectReasons", JsonValueKind.Null);
+
+        using var doc = JsonDocument.Parse(json);
+        Assert.False(doc.RootElement.TryGetProperty("hasMore", out _));
+        Assert.False(doc.RootElement.TryGetProperty("totalCount", out _));
+        Assert.False(doc.RootElement.TryGetProperty("limit", out _));
+        Assert.False(doc.RootElement.TryGetProperty("offset", out _));
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // POST/GET /v3/myAccount/documents[/files]/{id} -> AccountDocumentGetResponseDTO
+    // B-20f/B-20g regression: ViewDocumentFile e SubmitDocument antes retornavam
+    // AccountDocumentFile (com Name/Url ficticios) e AccountDocumentGroup
+    // (objeto rico). Schema real retorna apenas {id, status}.
+    // ─────────────────────────────────────────────────────────────
+
+    [Fact]
+    public void DocumentResponse_HasOnlyIdAndStatus()
+    {
+        var json = FixtureLoader.Load("AccountDocument/document-response.json");
+
+        var result = JsonContractAssert.DeserializeFixture<AccountDocument>(json);
+
+        Assert.Equal("8d257732-2220-11ec-b695-b6af4a64184d", result.Id);
+        Assert.Equal(AccountDocumentStatus.PENDING, result.Status);
+
+        // Regressao B-20f: schema NAO retorna name nem url
+        using var doc = JsonDocument.Parse(json);
+        Assert.False(doc.RootElement.TryGetProperty("name", out _));
+        Assert.False(doc.RootElement.TryGetProperty("url", out _));
+    }
+
+    [Fact]
+    public void DocumentStatus_AllFourValuesDeserialize()
+    {
+        // Schema AccountDocumentGetResponseDTO.status: NOT_SENT, PENDING, APPROVED, REJECTED
+        foreach (var status in new[] { "NOT_SENT", "PENDING", "APPROVED", "REJECTED" })
+        {
+            var json = $"{{\"id\":\"x\",\"status\":\"{status}\"}}";
+            var result = JsonContractAssert.DeserializeFixture<AccountDocument>(json);
+            Assert.Equal(status, result.Status.ToString());
+        }
+    }
+
+    [Fact]
+    public void DocumentGroupStatus_AllFiveValuesDeserialize()
+    {
+        // Schema AccountDocumentGroupResponseDTO.status tem 5 valores
+        // (Group ganha IGNORED em relacao ao Document).
+        foreach (var status in new[] { "NOT_SENT", "PENDING", "APPROVED", "REJECTED", "IGNORED" })
+        {
+            var json = $"{{\"id\":\"x\",\"status\":\"{status}\",\"type\":\"CUSTOM\",\"documents\":[]}}";
+            var result = JsonContractAssert.DeserializeFixture<AccountDocumentGroup>(json);
+            Assert.Equal(status, result.Status.ToString());
+        }
+    }
+
+    [Fact]
+    public void DocumentType_AllTwelveValuesDeserialize()
+    {
+        var values = new[] {
+            "ALLOW_BANK_ACCOUNT_DEPOSIT_STATEMENT", "CUSTOM", "EMANCIPATION_OF_MINORS",
+            "ENTREPRENEUR_REQUIREMENT", "IDENTIFICATION_SELFIE", "IDENTIFICATION",
+            "INVOICE", "MEI_CERTIFICATE", "MINUTES_OF_CONSTITUTION",
+            "MINUTES_OF_ELECTION", "POWER_OF_ATTORNEY", "SOCIAL_CONTRACT"
+        };
+
+        foreach (var type in values)
+        {
+            var json = $"{{\"id\":\"x\",\"status\":\"NOT_SENT\",\"type\":\"{type}\",\"documents\":[]}}";
+            var result = JsonContractAssert.DeserializeFixture<AccountDocumentGroup>(json);
+            Assert.Equal(type, result.Type.ToString());
+        }
+    }
+
+    [Fact]
+    public void ResponsibleType_AllThirteenValuesDeserialize()
+    {
+        var values = new[] {
+            "ALLOW_BANK_ACCOUNT_DEPOSIT_STATEMENT", "ASAAS_ACCOUNT_OWNER_EMANCIPATION_AGE",
+            "ASAAS_ACCOUNT_OWNER", "ASSOCIATION", "BANK_ACCOUNT_OWNER_EMANCIPATION_AGE",
+            "BANK_ACCOUNT_OWNER", "CUSTOM", "DIRECTOR", "INDIVIDUAL_COMPANY",
+            "LIMITED_COMPANY", "MEI", "PARTNER", "POWER_OF_ATTORNEY"
+        };
+
+        foreach (var t in values)
+        {
+            var json = $"{{\"name\":\"John\",\"type\":[\"{t}\"]}}";
+            var result = JsonContractAssert.DeserializeFixture<AccountDocumentResponsible>(json);
+            Assert.Single(result.Type);
+            Assert.Equal(t, result.Type[0].ToString());
+        }
+    }
+
+    // ─────────────────────────────────────────────────────────────
+    // POST multipart request — B-20h regression
+    // Schema oficial: campos sao "documentFile" (binary) e "type" (enum).
+    // C# properties devem ser DocumentFile e Type (FirstCharToLower converte).
+    // ─────────────────────────────────────────────────────────────
+
+    [Fact]
+    public void UploadRequest_HasCorrectMultipartFieldNames()
+    {
+        // Reflexao sobre as propriedades: garantir que C# property names viram
+        // os field names esperados pelo schema apos firstCharToLower do BaseManager.
+        var props = typeof(UploadAccountDocumentRequest).GetProperties();
+        var names = new System.Collections.Generic.HashSet<string>();
+        foreach (var p in props)
+        {
+            var firstLower = char.ToLowerInvariant(p.Name[0]) + p.Name.Substring(1);
+            names.Add(firstLower);
+        }
+
+        Assert.Contains("documentFile", names);
+        Assert.Contains("type", names);
+
+        // Regressao B-20h: nao deve mais existir "file" (antes era File: IAsaasFile)
+        // nem "documentType" (antes era DocumentType: string).
+        Assert.DoesNotContain("file", names);
+        Assert.DoesNotContain("documentType", names);
+    }
+}

Codout.Apis.Asaas.Tests/Contract/AnticipationContractTests.cs

@@ -0,0 +1,60 @@
+using System;
+using Codout.Apis.Asaas.Models.Anticipation;
+using Codout.Apis.Asaas.Models.Anticipation.Enums;
+
+namespace Codout.Apis.Asaas.Tests.Contract;
+
+/// <summary>
+/// Contract tests para AnticipationManager (B-30).
+/// Schemas verificados via MCP em 2026-05-24.
+/// </summary>
+public class AnticipationContractTests
+{
+    [Fact]
+    public void AnticipationResponse_DeserializesFromOfficialFixture()
+    {
+        var json = FixtureLoader.Load("Anticipation/anticipation-response.json");
+
+        var result = JsonContractAssert.DeserializeFixture<Anticipation>(json);
+
+        Assert.Equal("receivableAnticipation", result.Object);
+        Assert.Equal("9e7d8639-350f-45c0-8bc3-d4ddc5f4ebac", result.Id);
+        Assert.Equal("pay_626366773834", result.PaymentId);
+        Assert.Null(result.InstallmentId);
+        Assert.Equal(AnticipationStatus.PENDING, result.Status);
+        Assert.Equal(new DateTime(2019, 5, 20), result.AnticipationDate);
+        Assert.Equal(new DateTime(2019, 5, 26), result.DueDate);
+        Assert.Equal(new DateTime(2019, 5, 14), result.RequestDate);
+        Assert.Equal(2.33m, result.Fee);
+        Assert.Equal(5, result.AnticipationDays);
+        Assert.Equal(73.68m, result.NetValue);
+        Assert.Equal(80m, result.TotalValue);
+        Assert.Equal(76.01m, result.Value);
+        Assert.Null(result.DenialObservation);
+    }
+
+    [Fact]
+    public void AnticipationResponse_NullableDatesHandleMissing()
+    {
+        // B-30a: AnticipationDate, DueDate, RequestDate eram non-nullable.
+        var json = "{\"id\":\"a_x\",\"status\":\"PENDING\"}";
+
+        var result = JsonContractAssert.DeserializeFixture<Anticipation>(json);
+
+        Assert.Null(result.AnticipationDate);
+        Assert.Null(result.DueDate);
+        Assert.Null(result.RequestDate);
+    }
+
+    [Fact]
+    public void AnticipationStatus_AllSevenValuesDeserialize()
+    {
+        foreach (var status in new[] {
+            "PENDING", "DENIED", "CREDITED", "DEBITED", "CANCELLED", "OVERDUE", "SCHEDULED" })
+        {
+            var json = $"{{\"id\":\"x\",\"status\":\"{status}\"}}";
+            var result = JsonContractAssert.DeserializeFixture<Anticipation>(json);
+            Assert.Equal(status, result.Status.ToString());
+        }
+    }
+}

Codout.Apis.Asaas.Tests/Contract/AsaasAccountContractTests.cs

@@ -0,0 +1,36 @@
+using System;
+using Codout.Apis.Asaas.Models.AsaasAccount;
+using Codout.Apis.Asaas.Models.Common.Enums;
+
+namespace Codout.Apis.Asaas.Tests.Contract;
+
+/// <summary>
+/// Contract tests para AsaasAccountManager (B-39).
+/// Schemas verificados via MCP em 2026-05-24.
+/// </summary>
+public class AsaasAccountContractTests
+{
+    [Fact]
+    public void AccountResponse_DeserializesAllFields()
+    {
+        var json = "{\"object\":\"account\",\"id\":\"4f468235-cec3-482f-b3d0-348af4c7194\",\"name\":\"John Doe\",\"email\":\"john.doe@asaas.com.br\",\"loginEmail\":\"john.doe@asaas.com.br\",\"phone\":null,\"mobilePhone\":null,\"address\":\"Rua Fernando Orlandi\",\"addressNumber\":\"544\",\"province\":\"Jardim Pedra Branca\",\"postalCode\":\"14079-452\",\"cpfCnpj\":\"35381637000150\",\"birthDate\":\"1995-04-12\",\"personType\":\"JURIDICA\",\"companyType\":\"MEI\",\"city\":15478,\"state\":\"SP\",\"country\":\"Brasil\",\"tradingName\":null,\"site\":\"https://www.example.com\",\"walletId\":\"c0c1688f-636b-42c0-b6ee-7339182276b7\",\"accountNumber\":{\"agency\":\"0001\",\"account\":\"3514\",\"accountDigit\":\"3\"},\"commercialInfoExpiration\":{\"isExpired\":false,\"scheduledDate\":\"2025-05-05 00:00:00\"}}";
+
+        var result = JsonContractAssert.DeserializeFixture<Account>(json);
+
+        Assert.Equal("account", result.Object);
+        Assert.Equal("4f468235-cec3-482f-b3d0-348af4c7194", result.Id);
+        Assert.Equal("John Doe", result.Name);
+        Assert.Equal(PersonType.JURIDICA, result.PersonType);
+        Assert.Equal(CompanyType.MEI, result.CompanyType);
+        // B-39a: City era string, agora int
+        Assert.Equal(15478L, result.City);
+        Assert.Equal("SP", result.State);
+        Assert.Equal(new DateTime(1995, 4, 12), result.BirthDate);
+        Assert.Equal("c0c1688f-636b-42c0-b6ee-7339182276b7", result.WalletId);
+        // B-39b: campos novos
+        Assert.NotNull(result.AccountNumber);
+        Assert.Equal("0001", result.AccountNumber.Agency);
+        Assert.NotNull(result.CommercialInfoExpiration);
+        Assert.False(result.CommercialInfoExpiration.IsExpired);
+    }
+}