Repository navigation
Conversation
Generate customer inputs, resource methods and XML documentation from a pinned public specification while preserving dictionary-based calls. BREAKING CHANGE: Customer.SatValidatedAt and Customer.EditLinkExpiresAt now use nullable DateTime values. Handle absent dates before reading their values.
Cover all public API operations with generated wrappers, typed inputs and responses, XML documentation and schema-selected workflow variants. Preserve dictionary calls and add local webhook verification. BREAKING CHANGE: Response models and method results now follow the API v2 contract, including retention models, typed ZIP requests, nullable fields, decimals and collection results. Update manual interfaces and follow the v8 migration guide.
javorosas
changed the title
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Active issues remain, including a critical union deserialization bug that can select the wrong object type and discard payload fields, along with a moderate API collision and documentation typos.
5 open issues
What changed in this PR
Generates the complete typed .NET SDK from a pinned API v2 OpenAPI contract, covering 128 operations across 12 resource wrappers while preserving dictionary-based compatibility.
Changes:
- Added generated request and response models, complements, catalogs, filters, unions, and webhook event types.
- Expanded wrappers, transport handling, downloads, uploads, error details, and local webhook verification.
- Added deterministic generation tooling, CI validation, compatibility tests, release metadata, and migration documentation.
| File | Description |
|---|---|
| Wrappers/IComercioExteriorCatalogWrapper.cs | Defines the commerce-exterior catalog wrapper interface. |
| Wrappers/BaseWrapper.Requests.cs | Provides shared typed request, multipart, download, response, and error handling. |
| Wrappers/BaseWrapper.cs | Defines common wrapper transport and request infrastructure. |
| Serialization/OneOfConverter.cs | Implements JSON serialization and deserialization for heterogeneous union values. |
| scripts/sync-openapi.mjs | Synchronizes and validates the pinned OpenAPI specification. |
| Router/WebhookRouter.cs | Contains webhook routing behavior for the generated API surface. |
| Router/ToolRouter.cs | Contains tool-related routing behavior. |
| Router/Router.cs | Provides shared query serialization for typed and dictionary parameters. |
| Router/RetentionRouter.cs | Contains retention-related routing behavior. |
| Router/ReceiptRouter.cs | Contains receipt-related routing behavior. |
| Router/ProductRouter.cs | Contains product-related routing behavior. |
| Router/NominaCatalogRouter.cs | Contains payroll catalog routing behavior. |
| Router/HealthRouter.cs | Contains API health routing behavior. |
| Router/CustomerRouter.cs | Contains customer-related routing behavior. |
| Router/CatalogRouter.cs | Contains general catalog routing behavior. |
| Router/CartaporteCatalogRouter.cs | Contains Carta Porte catalog routing behavior. |
| package.json | Defines SDK generation scripts and pinned tooling dependencies. |
| openapi/source.json | Records the pinned OpenAPI source metadata. |
| Models/ZipCode.cs | Defines the generated ZIP code response model. |
| Models/ToInvoiceSummary.cs | Defines the generated invoice summary model. |
| Models/TaxInfoValidation.cs | Defines tax information validation results. |
| Models/TaxInfoError.cs | Defines tax information validation errors. |
| Models/TaxIdValidation.cs | Defines tax identifier validation results. |
| Models/SignedDownloadUrl.cs | Defines signed download URL responses. |
| Models/SeriesGroup.cs | Defines series group data. |
| Models/SendRetentionByEmailResponse.cs | Defines retention email operation responses. |
| Models/SendReceiptByEmailResponse.cs | Defines receipt email operation responses. |
| Models/SendInvoiceByEmailResponse.cs | Defines invoice email operation responses. |
| Models/SelfInvoiceSettings.cs | Defines self-invoicing settings. |
| Models/SearchCartaPorteNavalAuthorizationsResponseDataItem.cs | Defines Carta Porte naval authorization search items. |
| Models/RetentionTotals.cs | Defines retention totals. |
| Models/RetentionRetainedTax.cs | Defines retained tax details. |
| Models/RetentionPeriod.cs | Defines retention period data. |
| Models/RelatedResourceMessage.cs | Defines related resource messages. |
| Models/ReceiptInvoiceSummaryTax.cs | Defines receipt invoice summary tax data. |
| Models/ProductCategoryList.cs | Defines product category list responses. |
| Models/ProductCategoryDetail.cs | Defines product category detail data. |
| Models/ProductCategory.cs | Defines product category data. |
| Models/PaymentSummaryTax.cs | Defines payment summary tax data. |
| Models/PaymentRelatedDocumentsItemTaxesItem.cs | Defines taxes for related payment documents. |
| Models/PaymentRelated.cs | Defines related payment data. |
| Models/OrganizationTeamRoleTemplate.cs | Defines organization team role templates. |
| Models/OrganizationSeriesDeletion.cs | Defines organization series deletion responses. |
| Models/OrganizationPendingPlanUpdate.cs | Defines pending organization plan updates. |
| Models/OrganizationPendingAddOnsUpdate.cs | Defines pending organization add-on updates. |
| Models/OrganizationDeleteCerts.cs | Defines organization certificate deletion data. |
| Models/OneOf3.cs | Defines a generated three-way union model. |
| Models/OneOf2.cs | Defines a generated two-way union model. |
| Models/OkResponse.cs | Defines the standard successful operation response. |
| Models/NominaSubContratacionProperties.cs | Defines payroll subcontracting properties. |
| Models/NominaSeparacionProperties.cs | Defines payroll separation properties. |
| Models/NominaPercepcionesProperties.cs | Defines payroll perception properties. |
| Models/NominaJubilacionProperties.cs | Defines payroll retirement properties. |
| Models/NominaIncapacidadProperties.cs | Defines payroll incapacity properties. |
| Models/NominaHorasExtraProperties.cs | Defines payroll overtime properties. |
| Models/NominaEmisorPropertiesEntidadSncf.cs | Defines payroll issuer SNCF entity properties. |
| Models/NominaEmisorProperties.cs | Defines payroll issuer properties. |
| Models/NominaDeduccionProperties.cs | Defines payroll deduction properties. |
| Models/NominaCompensacionProperties.cs | Defines payroll compensation properties. |
| Models/NominaAccionesProperties.cs | Defines payroll stock action properties. |
| Models/Namespace.cs | Defines namespace-related model data. |
| Models/LocalTax.cs | Defines local tax data. |
| Models/LiveApiKey.cs | Defines live API key data. |
| Models/LeyendasFiscalesDataLeyendasItem.cs | Defines individual fiscal legend data. |
| Models/LeyendasFiscalesData.cs | Defines fiscal legend collections. |
| Models/InvoiceItemThirdParty.cs | Defines third-party invoice item data. |
| Models/InvoiceItemPart.cs | Defines invoice item part data. |
| Models/InvoiceComplementProperties.cs | Defines invoice complement properties. |
| Models/InvoiceCancellation.cs | Defines invoice cancellation data. |
| Models/Inputs/WebhookUpdateInput.cs | Defines typed webhook update input data. |
| Models/Inputs/WebhookCreateInput.cs | Defines typed webhook creation input data. |
| Models/Inputs/ToolValidateTaxIdParams.cs | Defines parameters for tax identifier validation. |
| Models/Inputs/SendRetentionByEmailInput.cs | Defines retention email request input. |
| Models/Inputs/SendReceiptByEmailInput.cs | Defines receipt email request input. |
| Models/Inputs/SendInvoiceByEmailInput.cs | Defines invoice email request input. |
| Models/Inputs/SendEditLinkByEmailInput.cs | Defines edit-link email request input. |
| Models/Inputs/RelatedDocumentInput.cs | Defines related document input data. |
| Models/Inputs/ReceiptAssignCustomerInput.cs | Defines receipt customer assignment input. |
| Models/Inputs/PagoComplementInput.cs | Defines payment complement input data. |
| Models/Inputs/OrganizationUserAccessRoleUpdateInput.cs | Defines organization user access role updates. |
| Models/Inputs/OrganizationSeriesUpdateInput.cs | Defines organization series update input. |
| Models/Inputs/OrganizationSeriesDefaultInput.cs | Defines organization default series input. |
| Models/Inputs/OrganizationSeriesCreateInput.cs | Defines organization series creation input. |
| Models/Inputs/OrganizationSelfInvoiceInput.cs | Defines organization self-invoice input. |
| Models/Inputs/OrganizationPermissionRoleUpdateInput.cs | Defines organization permission role update input. |
| Models/Inputs/OrganizationLogoInput.cs | Defines organization logo upload input. |
| Models/Inputs/OrganizationInviteRespondInput.cs | Defines organization invitation response input. |
| Models/Inputs/OrganizationInviteCreateInput.cs | Defines organization invitation creation input. |
| Models/Inputs/OrganizationDomainInput.cs | Defines organization domain input. |
| Models/Inputs/OrganizationCustomizationInputPdfExtraPayrollOptions.cs | Defines organization PDF payroll customization options. |
| Models/Inputs/OrganizationCreateInput.cs | Defines organization creation input. |
| Models/Inputs/OrganizationCheckDomainIsAvailableParams.cs | Defines organization domain availability parameters. |
| Models/Inputs/NominaSubContratacionInput.cs | Defines payroll subcontracting input. |
| Models/Inputs/NominaReceptorNestedInput.cs | Defines nested payroll recipient input. |
| Models/Inputs/NominaPercepcionNestedInput.cs | Defines nested payroll perception input. |
| Models/Inputs/NominaPercepcionesInput.cs | Defines payroll perceptions input. |
| Models/Inputs/NominaEntidadSncfInput.cs | Defines payroll SNCF entity input. |
| Models/Inputs/NominaEmisorInputEntidadSncf.cs | Defines payroll issuer SNCF entity input. |
| Models/Inputs/NominaComplementInput.cs | Defines payroll complement input. |
| Models/Inputs/NominaCatalogSearchPerceptionsParams.cs | Defines payroll perception catalog search parameters. |
| Models/Inputs/NominaCatalogSearchDeductionsParams.cs | Defines payroll deduction catalog search parameters. |
| Models/Inputs/NominaAccionesInput.cs | Defines payroll actions input. |
| Models/Inputs/NamespaceInput.cs | Defines namespace input data. |
| Models/Inputs/LeyendasFiscalesInput.cs | Defines fiscal legends input. |
| Models/Inputs/LeyendasFiscalesDataInputLeyendasItem.cs | Defines individual fiscal legend input items. |
| Models/Inputs/LeyendasFiscalesDataInput.cs | Defines fiscal legends collection input. |
| Models/Inputs/InvoiceStampDraftParams.cs | Defines invoice draft stamping parameters. |
| Models/Inputs/InvoiceItemThirdPartyInput.cs | Defines third-party invoice item input. |
| Models/Inputs/InvoiceItemInputThirdParty.cs | Defines nested third-party invoice item input. |
| Models/Inputs/InvoiceGetPaymentSummaryParams.cs | Defines invoice payment summary parameters. |
| Models/Inputs/InvoiceCreateParams.cs | Defines invoice creation parameters. |
| Models/Inputs/InvoiceComplementInput.cs | Defines invoice complement input. |
| Models/Inputs/InvoiceableCommonInputPdfOptionsPayrollOptions.cs | Defines payroll PDF options for invoiceable inputs. |
| Models/Inputs/InvoiceableCommonEditInputPdfOptionsPayrollOptions.cs | Defines payroll PDF options for invoiceable edits. |
| Models/Inputs/CustomerUpdateParams.cs | Defines customer update parameters. |
| Models/Inputs/CustomerCreateParams.cs | Defines customer creation parameters. |
| Models/Inputs/CustomerComercioExteriorInput.cs | Defines customer foreign-trade input. |
| Models/Inputs/CustomComplementInput.cs | Defines custom complement input. |
| Models/Inputs/ComercioExteriorReceptorInput.cs | Defines foreign-trade recipient input. |
| Models/Inputs/ComercioExteriorMercanciasInput.cs | Defines foreign-trade goods input. |
| Models/Inputs/ComercioExteriorInput.cs | Defines foreign-trade complement input. |
| Models/Inputs/ComercioExteriorEmisorInput.cs | Defines foreign-trade issuer input. |
| Models/Inputs/ComercioExteriorDataInputPropietarioItem.cs | Defines foreign-trade owner input items. |
| Models/Inputs/ComercioExteriorDataInputDestinatarioItem.cs | Defines foreign-trade recipient input items. |
| Models/Inputs/CatalogSearchTaxSystemsParams.cs | Defines tax system catalog search parameters. |
| Models/Inputs/CatalogSearchInvoiceUsesParams.cs | Defines invoice use catalog search parameters. |
| Models/Inputs/CatalogSearchCountriesParams.cs | Defines country catalog search parameters. |
| Models/Inputs/CartaPorteRemolqueInput.cs | Defines Carta Porte trailer input. |
| Models/Inputs/CartaPorteInput.cs | Defines Carta Porte complement input. |
| Models/Inputs/CartaPorteGuiaIdentificacionInput.cs | Defines Carta Porte guide identification input. |
| Models/Inputs/CartaPorteDocumentacionAduaneraInput.cs | Defines customs documentation input. |
| Models/Inputs/CartaPorteDerechosDePasoInput.cs | Defines right-of-way input. |
| Models/Inputs/CartaPorteDataPropertiesInputFiguraTransporteItemPartesTransporteItem.cs | Defines Carta Porte transport parts input items. |
| Models/Inputs/CartaPorteContenedorMaritimoInputRemolquesCCPItem.cs | Defines maritime container trailer input items. |
| Models/Inputs/CartaPorteContenedorFerroviarioInput.cs | Defines railway container input. |
| Models/Inputs/CancellationWithSubstitutionInput.cs | Defines cancellation input with substitution. |
| Models/Inputs/CancellationQueryInput.cs | Defines cancellation query input. |
| Models/IeduComplement.cs | Defines education complement data. |
| Models/Global.cs | Defines shared global model data. |
| Models/FielCertificate.cs | Defines FIEL certificate data. |
| Models/ErrorDetail.cs | Defines typed API error details. |
| Models/EfosData.cs | Defines EFOS data. |
| Models/Efos.cs | Defines EFOS response data. |
| Models/DomainAvailability.cs | Defines domain availability results. |
| Models/CustomizationPdfExtraPayrollOptions.cs | Defines PDF payroll customization options. |
| Models/CustomizationDefaultSeries.cs | Defines default series customization data. |
| Models/CustomerInfo.cs | Defines customer information data. |
| Models/CustomerEditLinkEmailResult.cs | Defines customer edit-link email results. |
| Models/CompletionStep.cs | Defines completion step data. |
| Models/ComercioExteriorMercancias.cs | Defines foreign-trade goods data. |
| Models/ComercioExteriorEmisor.cs | Defines foreign-trade issuer data. |
| Models/ComercioExteriorDescripcionesEspecificas.cs | Defines foreign-trade specific descriptions. |
| Models/ComercioExteriorDataPropertiesReceptor.cs | Defines foreign-trade recipient properties. |
| Models/ComercioExteriorDataPropertiesPropietarioItem.cs | Defines foreign-trade owner property items. |
| Models/ComercioExteriorDataPropertiesDestinatarioItem.cs | Defines foreign-trade recipient property items. |
| Models/CheckApiHealthResponse.cs | Defines API health check responses. |
| Models/Certificate.cs | Defines certificate data. |
| Models/CatalogItem.cs | Defines common catalog item data. |
| Models/CartaPorteTransporteFerroviario.cs | Defines railway transport data. |
| Models/CartaPorteRemolque.cs | Defines trailer data. |
| Models/CartaPorteIdentificacionVehicular.cs | Defines vehicle identification data. |
| Models/CartaPorteGuiaIdentificacion.cs | Defines guide identification data. |
| Models/CartaPorteDocumentacionAduanera.cs | Defines customs documentation data. |
| Models/CartaPorteDetalleMercancia.cs | Defines merchandise detail data. |
| Models/CartaPorteDerechosDePaso.cs | Defines right-of-way data. |
| Models/CartaPorteDataPropertiesFiguraTransporteItemPartesTransporteItem.cs | Defines transport figure part items. |
| Models/CartaPorteContenedorMaritimoRemolquesCCPItem.cs | Defines maritime container trailer data. |
| Models/CartaPorteContenedorFerroviario.cs | Defines railway container data. |
| Models/CartaPorteCarroFerroviario.cs | Defines railway car data. |
| Models/CartaPorteCantidadTransporta.cs | Defines transported quantity data. |
| Models/CartaPorteAutotransporte.cs | Defines motor transport data. |
| Models/ApiEventData.JsonConverter.cs | Provides JSON conversion for API event data. |
| Models/ApiEventData.cs | Defines API event payload data. |
| IFacturapiClient.cs | Extends the public client contract with generated API capabilities. |
| FacturapiTest/ClientCompatibilityTests.cs | Tests compatibility behavior for the updated client models and interfaces. |
| FacturAPIException.cs | Exposes typed error details while preserving raw API error data. |
| FacturapiClient.cs | Implements the public client and generated wrapper bindings. |
| facturapi-net.csproj | Configures the multi-target SDK project and version 8.0.0 package metadata. |
| CHANGELOG.md | Documents the SDK release changes and migration guidance. |
| .gitignore | Ignores SDK generation dependencies and local generated-tooling artifacts. |
| .github/workflows/ci.yml | Runs build, test, and generated-source verification in CI. |
Review effort: Lite
Comment on lines
+39
to
+40
| token.Type == JTokenType.Object && !type.IsValueType && type != typeof(string) && (!typeof(IEnumerable).IsAssignableFrom(type) || typeof(IDictionary).IsAssignableFrom(type))) | ||
| return Activator.CreateInstance(unionType, BindingFlags.Instance | BindingFlags.NonPublic, null, new[] { token.ToObject(type, serializer) }, null); |
| /// Opcional. | ||
| /// </summary> | ||
| [JsonIgnore] | ||
| public new List<string>? Add |
| { | ||
| public bool Available { get; set; } | ||
| /// <summary> | ||
| /// Indica si el dominio está diponible |
| public bool? IsValid { get; set; } = default!; | ||
|
|
||
| /// <summary> | ||
| /// Objeto con el resultado de la búqueda ante el SAT. |
| public class PaymentRelatedDocumentsItemTaxesItem | ||
| { | ||
| /// <summary> | ||
| /// Base utilizada para el cálculo del impuestos. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Generate the .NET SDK from the pinned public API v2 specification, covering all 128 HTTP operations across 12 resource wrappers. Requests can use typed input models or the established dictionary arguments; responses and XML documentation follow the public contract.
SDK coverage
Best-effort typing
OneOf, preserving their JSON shape. Concrete complement inputs are assignable to their broader family.DateTimeandDateTimeOffsetin date-time inputs. Preserve open JSON values and local SAT date strings.Transport and webhooks
Keep shared HTTP error handling, cancellation, seekable downloads and multipart behavior. Verify webhook HMAC SHA-256 locally against the original payload bytes, with typed event objects selected from the declared resource type. The explicit remote verification method preserves string or object payload responses.
Compatibility — 8.0.0
Response models and results now match the API contract, including nullable dates and optional fields, decimals, retention results, typed ZIP requests and documented collection responses for API keys and series. Receipt invoicing and email operations expose their results. Manual wrapper/client implementations must update their interfaces. The README contains migration guidance and examples.
Verification