SDK y modelosSDK y modelos

SDK y modelos

El payload de emisión (POST /ecf) tiene decenas de campos anidados. En lugar de reconstruirlo a mano, puedes usar los modelos ya escritos en tu lenguaje: se generan automáticamente desde el mismo documento OpenAPI que alimenta la Referencia de API, así que siempre coinciden con lo que la API acepta y devuelve.

TypeScriptInterfaces para Node, Bun o el navegador.

PythonDataclasses sin dependencias externas.

C#Records con System.Text.Json.

PHPClases 8.1 con propiedades readonly.

Descargas

Recurso	Descarga
Documento OpenAPI (JSON)	novafe-public.json
Modelos TypeScript (zip)	novafe-models-typescript.zip
Modelos Python (zip)	novafe-models-python.zip
Modelos C# (zip)	novafe-models-csharp.zip
Modelos PHP (zip)	novafe-models-php.zip

Cada zip trae un archivo por área de la API (ecf, sequences, webhooks, received-ecf, organizations, entre otros) más common, con los tipos que comparten varias áreas.

Qué incluyen y qué no

Los modelos describen la forma de cada request y respuesta. Antes de usarlos conviene tener presente:

La obligatoriedad de los campos depende del tipo de e-CF. Los modelos marcan como requeridos solo los campos que lo son siempre (type y lines en la emisión). El resto es opcional en el modelo aunque un tipo concreto lo exija: consulta la matriz de obligatoriedad por tipo y usa validar sin emitir para comprobar tu payload.
Las fechas son texto. El payload usa dd-MM-yyyy (por ejemplo 15-03-2026) y las respuestas traen fecha y hora con la zona horaria de República Dominicana. Los modelos las dejan como string a propósito.
Los montos aceptan número o texto. La API acepta 2360.5 y "2360.5". Los modelos usan el tipo decimal de cada lenguaje cuando existe (Python serializa Decimal como texto para no perder precisión).
Los códigos van como texto o entero, no como enumeración. Los valores permitidos (por ejemplo el kind de una línea o el tipo de pago) están en el comentario de cada campo y en la Referencia de API.

Genera un cliente completo con herramientas oficiales

Si prefieres un SDK con cliente HTTP y no solo modelos, alimenta cualquiera de estas herramientas con el documento OpenAPI descargable:

# TypeScript (tipos)
npx openapi-typescript novafe-public.json -o novafe.d.ts

# Python (modelos Pydantic)
datamodel-codegen --input novafe-public.json --output novafe_models.py

# C# (cliente completo)
dotnet tool install -g NSwag.ConsoleCore
nswag openapi2csclient /input:novafe-public.json /output:NovaFEClient.cs

# PHP (u otro lenguaje) con OpenAPI Generator
openapi-generator-cli generate -i novafe-public.json -g php -o novafe-php

Cómo se mantienen actualizados

Los archivos de esta sección se regeneran en cada publicación del manual a partir del documento OpenAPI vigente, por lo que no requieren mantenimiento manual. Si algo de la API cambia, cambia aquí en la misma publicación.