Note: @nodecfdi/cfdiutils-elements is now deprecated. Use @nodecfdi/cfdi-elements.
Sub-library of nodecfdi/cfdiutils for cfdi struct data
🇺🇸 The documentation of this project is in spanish as this is the natural language for intended audience.
🇲🇽 La documentación del proyecto está en español porque ese es el lenguaje principal de los usuarios.
Librería para contener las estructuras de datos que componen un cfdi. Inspirada por la versión de php https://github.com/eclipxe13/CfdiUtils
npm i @nodecfdi/cfdiutils-elements --saveyarn add @nodecfdi/cfdiutils-elements --savepnpm add @nodecfdi/cfdiutils-elementsLa librería @nodecfdi/cfdiutils-elements es una especialización de CNodes.
Se trata solo de una estructura de datos, no caigas en la tentación de insertar lógica más allá de la propia estructura.
Todo elemento es un nodo, entonces todos los métodos y propiedades de CNodeInterface están presentes.
Entonces, para escribir atributos se recomienda usar la forma de arreglo, por ejemplo:
comprobante.attributes().set('Descuento','1234.56') para establecer el atributo "Descuento" a "1234.56".
Cualquier elemento debe cumplir con la interfaz ElementInterface
que es una extensión de CNodeInterface y agrega:
getElementName(): string: Devuelve el nombre del elemento, comocfdi:ComplementogetFixedAttributes(): array: Establece la lista de nodos predefinidos al crearse (útil para Complementos y Comprobante)getChildrenOrder(): array: establece el orden de los nodos hijos
En última instancia, un elemento (ElementInterface) es un nodo (CNodeInterface)
por lo que puedes utilizar a bajo nivel todo el poder de los nodos para trabajar con esta estructura de datos.
Los elementos deberían seguir esta nomenclatura genérica para nombrar sus métodos.
La nomenclatura con el prefijo get* se escribe en la forma ElementoPadre.getElementoHijo(): ElementoHijo
y se espera devolver una única instancia de ElementoHijo. Si la instancia no existe entonces se crea.
La nomenclatura con el prefijo add* se escribe la forma ElementoPadre.addElementoHijo(attributes): ElementoHijo
y se espera crear una instancia de ElementoHijo con los atributos datos, agregarla a los hijos de ElementoPadre
y la instancia de ElementoHijo creada.
Cuando se utiliza add* hay dos comportamientos esperados:
- Si solo debe haber un hijo de un determinado tipo, entonces no se crea uno nuevo y se ocupa el existente.
- Si puede haber más de un hijo de un determinado tipo, entonces se crea uno nuevo y se agrega a los hijos.
Por eso, como solo debe haber un nodo emisor dentro de un comprobante,
entonces Comprobante.addEmisor({'RegimenFiscal' : '601'}) tiene este comportamiento:
- Se obtiene el elemento
Emisor, si no existe se crea uno vacío. - Se escriben los atributos pasados al elemento obtenido.
- Se devuelve el elemento.
Por el contrario, como puede haber varios Cfdi Relacionados, entonces
CfdiRelacionados.addCfdiRelacionado({ 'UUID' : uuid }) tiene este comportamiento:
- Se crea un elemento de tipo
CfdiRelacionadocon los atributos pasados. - Se agrega el elemento recién creado a los hijos de
CfdiRelacionados. - Se devuelve el elemento creado.
Existe un caso donde lo que se espera entregar como atributo al prefijo add* es en realidad un hijo. Esto sucede
en addComplemento y addAddenda.
La nomenclatura con el prefijo multi* se escribe la
forma ElementoPadre.multiElementoHijo(...attributes): ElementoPadre
y se espera crear múltiples una instancia de ElementoHijo con los atributos datos, agregarla a los hijos
de ElementoPadre
y la instancia de ElementoPadre creada.
Otra forma de decirlo: es como los métodos add* pero se le pueden mandar varios arreglos de atributos y se creará un
elemento para cada parámetro enviado.
Por lo anterior, CfdiRelacionados.multiCfdiRelacionado( {'UUID' : uuid1}, {'UUID' : uuid2}) agregará dos hijos y
devolverá la misma instancia del objeto llamado.
Puedes obtener soporte abriendo un ticket en Github.
Adicionalmente, esta librería pertenece a la comunidad OcelotlStudio, así que puedes usar los mismos canales de comunicación para obtener ayuda de algún miembro de la comunidad.
Esta librería se mantendrá compatible con al menos la versión con soporte activo de Node más reciente.
También utilizamos Versionado Semántico 2.0.0 por lo que puedes usar esta librería sin temor a romper tu aplicación.
Las contribuciones con bienvenidas. Por favor lee CONTRIBUTING para más detalles y recuerda revisar el archivo CHANGELOG.
The @nodecfdi/cfdiutils-elements library is copyright © NodeCfdi - OcelotlStudio and licensed for use under the MIT License (MIT). Please see LICENSE for more information.