Apariencia
Convenciones
Reglas de formato comunes a varias operaciones. Cada página de endpoint indica además sus reglas propias; si hay diferencia, manda la página del endpoint.
Documentos de identidad (RIF y cédula)
Una letra seguida de dígitos, sin guiones ni espacios: J123456789, V12345678.
| Letra | Tipo |
|---|---|
V | Venezolano |
E | Extranjero |
P | Pasaporte |
J | Jurídico |
G | Gubernamental |
C | Comuna / consejo comunal |
- Para el cliente se aceptan de 8 a 10 dígitos después de la letra.
- Las personas naturales son
VyE. - Si el cliente no existe, se registra automáticamente con los datos enviados (documento, nombre o razón social, correo, teléfono y dirección). Si ya existe, se usa el registrado.
Teléfono y correo
- Teléfono: 11 dígitos, por ejemplo
04141234567. Se ignoran espacios, guiones y paréntesis. - Correo: una dirección válida, por ejemplo
cliente@example.com.
Montos y cantidades
| Dato | Formato | Ejemplo |
|---|---|---|
| Precio de producto | Enteros con hasta 2 decimales, separador . o ,, sin separador de miles. Mayor que 0. | 150.50 |
| Cantidad | Número mayor que 0 con punto decimal | 2 · 1.5 |
| Monto de un pago | Hasta 9 enteros y exactamente 2 decimales (se acepta , o .), sin separador de miles | 349.16 |
| Tasa de cambio | Número positivo con hasta 6 enteros y 8 decimales, punto o coma | 236.4500 · 36.5 |
| Montos de retenciones | Coma decimal; ver cada página de retención | 1.250,00 |
- Todos los precios y montos de los documentos se expresan en bolívares (Bs.). La tasa del día se usa para calcular los equivalentes en divisas.
- El total de un documento no puede superar
999.999.999,99.
Fechas
- Formato general:
AAAA-MM-DD(por ejemplo2026-10-22), hora de Venezuela (America/Caracas). - La fecha de la tasa de cambio acepta
AAAA-MM-DDoDD-MM-AAAA. - La fecha de emisión del documento la asigna el servidor.
Tipos de impuesto (tipoImpuesto)
| Código | Alícuota | Uso |
|---|---|---|
G | 16 % | General |
R | 8 % | Reducida |
A | 31 % | Lujo (adicional) |
E | 0 % | Exento |
P | 0 % | Percibido |
X | 0 % | Exportación (solo con cliente de exportación) |
Si un producto ya está registrado, el tipoImpuesto enviado debe coincidir con el registrado.
IGTF
El IGTF (3 %) se aplica sobre la parte del pago hecha en divisas (divisa), salvo que el negocio sea Contribuyente Ordinario. Los pagos pueden sumar el total sin IGTF (el servidor lo agrega) o el total más el IGTF.
Pagos
- Hasta 5 formas de pago por documento;
divisasolo una vez y en primer lugar. transferenciaypago movilrequierenbancoy una referencia de 4 dígitos;pago movilrequiere además un teléfono de 11 dígitos. Los bancos válidos se consultan en Bancos y los métodos en Métodos de pago.- Un documento sin pagos queda registrado a crédito.
Números de documento
- El número de factura, nota o guía que asigna tu sistema: solo dígitos, máximo 19.
- Se compara como texto exacto:
005172y5172son documentos distintos. - El número de control lo asigna el servidor con el formato
00-00000000. Si el negocio no tiene números de control disponibles, la emisión se rechaza.
Límites
- Líneas de productos por documento: lo define la configuración del servicio. Si se supera, el documento se rechaza indicando el máximo.
- Código de producto: máximo 13 caracteres, sin espacios. Nombre y descripción: máximo 400 (70 en algunas operaciones; ver cada página).
Lotes y duplicados
Las operaciones de emisión reciben lotes (por ejemplo facturas[], guiasDeDespacho[]) y un campo con la cantidad enviada, que debe coincidir. Cada documento se guarda con sus propios datos. La respuesta separa los documentos guardados de los rechazados. Un número de documento que ya existe para el negocio no se vuelve a emitir: si se guardó al menos uno, la respuesta es 200 y los repetidos aparecen en la lista de errores; si todos estaban registrados, la respuesta es 409 con success: false.
