REST-API Sector Compra Venta
Esta documentación detalla los endpoints disponibles en el servicio de facturación para el sector de compra venta.
INVALIDOS y ERRORES COMUNES
- Método HTTP Inválido: Código 710 (POST requerido) o 711/730 (GET requerido).
- Token Inválido/Expirado: Código 701 (InvalidToken).
- Falta de Token: Código 700 (NoToken).
- JSON Malformado: Código 400 (BadJSON).
- Error de Validación (Campos faltantes/inválidos): Código 400 (ValidationError).
- Error Interno del Servidor: Código 500 (ServerError)
1. ENDPOINT: /token
- URL: /token
- Método: POST
- Descripción: Genera un token JWT para autenticación en los demás endpoints.
- Estructura JSON Request:
{ "cliente": {"nit": "string (numérico, > 0)",
"usuario": "string",
"password": "string",
"imeimac": "string"
}
}
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "TOKEN": "jwt_token..." }
2. ENDPOINT: /api_consultar_nit
- URL: /api_consultar_nit
- Método: POST
- Autenticación: Requiere Token
- Descripción: Verifica si un NIT es válido para facturación.
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"sucursal": int,
"pos": int,
"nitVerificacion": "string"
}
}
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "DESCRIPCION": "NIT ACTIVO", "CODIGO": 986 }
3. ENDPOINT: /api_consulta_paquete_facturas
- URL: /api_consulta_paquete_facturas
- Método: POST
- Autenticación: Requiere Token
- Descripción: Consulta el estado de un paquete de facturas.
- Estructura JSON Request:
{ "cliente": {"nit": "string (numérico)",
"fecha": "string (YYYY-MM-DD)"
}
}
- Respuestas Exitosas:
- 200 OK: Array de objetos con información del paquete.
4. ENDPOINT: /api_facturar_cafc
- URL: /api_facturar_cafc
- Método: POST
- Autenticación: Requiere Token
- Descripción: Emite una factura utilizando CAFC (Contingencia).
- Estructura JSON Request:
{ "cliente": { ... campos de ClienteFactura ... }, "factura": { "cabecera": { ... campos de CabeceraFacturaCafc ... }, "detalle": [ { ... campos de DetalleFactura ... } ]}
}
- Respuestas Exitosas:
- 200 OK: Mensaje de éxito con detalles de la transacción.
5. ENDPOINT: /api_download_xml
- URL: /api_download_xml
- Método: POST
- Autenticación: Requiere Token
- Descripción: Descarga un archivo GZIP con los XMLs de facturas en un rango de fechas.
- Estructura JSON Request:
{ "cliente": {"nit": "string (numérico)",
"fechaIni": "string (YYYY-MM-DD)",
"fechaFin": "string (YYYY-MM-DD)"
}
}
- Respuestas Exitosas:
- 200 OK: Archivo binario (application/gzip).
6. ENDPOINT: /api_facturar
- URL: /api_facturar
- Método: POST
- Autenticación: Requiere Token
- Descripción: Emite una factura estándar del sector educativo.
- Estructura JSON Request:
{ "cliente": {"nit": int,
"usuario": "string",
"password": "string",
"codigo_documentos_sector_id": int,
"sucursal": int,
"pos": int,
"actividadEconomica": "string",
"imeimac": "string"
},
"factura": { "cabecera": {"idTransaccion": "string",
"nombreRazonSocial": "string",
"correoElectronico": "string",
"codigoTipoDocumentoIdentidad": int,
"numeroDocumento": "string",
"complemento": "string (opcional)",
"codigoCliente": "string",
"codigoMetodoPago": int,
"numeroTarjeta": int (opcional),
"montoTotal": float,
"montoTotalSujetoIva": float,
"codigoMoneda": int,
"tipoCambio": float,
"montoTotalMoneda": float,
"montoGiftCard": float (opcional),
"descuentoAdicional": float (opcional),
"codigoExcepcion": int,
"usuario": "string",
"tipoFacturaDocumento": int
},
"detalle": [
{"actividadEconomica": "string",
"codigoProductoSin": int,
"codigoProducto": "string",
"descripcion": "string",
"cantidad": float,
"unidadMedida": int,
"precioUnitario": float,
"montoDescuento": float (opcional),
"subTotal": float,
"numeroSerie": "string",
"numeroImei": "string"
}
]
}
}
- Respuestas Exitosas:
- 200 OK: Objeto JSON con confirmación de emisión.
7. ENDPOINT: /api_facturar_credito_debito
- URL: /api_facturar_credito_debito
- Método: POST
- Autenticación: Requiere Token
- Descripción: Emite una Nota de Crédito/Débito.
- Estructura JSON Request:
- Similar a /api_facturar, valida contra esquema JSON 'creditoDebitoSchema.json' y campos básicos de cliente (nit, sucursal, pos).
- Respuestas Exitosas:
- 200 OK: Mensaje con detalles de la nota emitida.
8. ENDPOINT: /api_anular_credito_debito
- URL: /api_anular_credito_debito
- Método: POST
- Autenticación: Requiere Token
- Descripción: Anula una Nota de Crédito/Débito.
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"cuf": "string",
"codigoMotivo": int (1, 2, 3, 4)
}
}
- Respuestas Exitosas:
- 200 OK: Confirmación de anulación.
9. ENDPOINT: /api_reversion_credito_debito
- URL: /api_reversion_credito_debito
- Método: POST
- Autenticación: Requiere Token
- Descripción: Revierte una Nota de Crédito/Débito.
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"cuf": "string"
}
}
- Respuestas Exitosas:
- 200 OK: Confirmación de reversión.
10. ENDPOINT: /api_reversion
- URL: /api_reversion
- Método: POST
- Autenticación: Requiere Token
- Descripción: Revierte una Factura.
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"cuf": "string"
}
}
- Respuestas Exitosas:
- 200 OK: Confirmación de reversión.
11. ENDPOINT: /api_anular
- URL: /api_anular
- Método: POST
- Autenticación: Requiere Token
- Descripción: Anula una Factura.
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"cuf": "string",
"codigoMotivo": int
}
}
- Respuestas Exitosas:
- 200 OK: Confirmación de anulación.
12. ENDPOINT: /api_verifica_factura
- URL: /api_verifica_factura
- Método: POST
- Autenticación: Requiere Token
- Descripción: Verifica el estado de una factura en la BD.
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"cuf": "string"
}
}
- Respuestas Exitosas:
- 200 OK: Detalle del estado de la factura.
13. ENDPOINT: /api_consulta_actividades_clientes
- URL: /api_consulta_actividades_clientes
- Método: POST
- Autenticación: Requiere Token
- Descripción: Consulta las actividades económicas de un cliente.
- Estructura JSON Request:
{ "cliente": {"nit": "string"
}
}
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "ACLIENTES": [...] }
14. ENDPOINT: /api_consulta_sectores_clientes
- URL: /api_consulta_sectores_clientes
- Método: POST
- Autenticación: Requiere Token
- Descripción: Consulta sectores.
- Estructura JSON Request:
{ "cliente": {"nit": "string"
}
}
- Respuestas Exitosas:
- 200 OK: Datos de sectores.
15. ENDPOINT: /api_consulta_sucursales
- URL: /api_consulta_sucursales
- Método: POST
- Autenticación: Requiere Token
- Descripción: Consulta sucursales.
- Estructura JSON Request:
{ "cliente": {"nit": "string"
}
}
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "SUCURSALES": [...] }
16. ENDPOINT: /api_consulta_motivos
- URL: /api_consulta_motivos
- Método: GET
- Autenticación: Requiere Token
- Descripción: Lista motivos de anulación.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "MOTIVOS": [...] }
17. ENDPOINT: /api_consulta_metodo_pago
- URL: /api_consulta_metodo_pago
- Método: GET
- Autenticación: Requiere Token
- Descripción: Lista métodos de pago.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "MPAGO": [...] }
18. ENDPOINT: /api_consulta_tipo_moneda
- URL: /api_consulta_tipo_moneda
- Método: GET
- Autenticación: Requiere Token
- Descripción: Lista tipos de moneda.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "MONEDAS": [...] }
19. ENDPOINT: /api_consulta_unidad_medida
- URL: /api_consulta_unidad_medida
- Método: GET
- Autenticación: Requiere Token
- Descripción: Lista unidades de medida.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "UMEDIDA": [...] }
20. ENDPOINT: /api_consulta_documento_identidad
- URL: /api_consulta_documento_identidad
- Método: GET
- Autenticación: Requiere Token
- Descripción: Lista tipos de documento de identidad.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "DOCIDEN": [...] }
21. ENDPOINT: /api_consulta_productos_sin
- URL: /api_consulta_productos_sin
- Método: POST
- Autenticación: Requiere Token
- Descripción: Consulta productos homologados por el SIN.
- Estructura JSON Request:
{ "cliente": {"nit": "string"
}
}
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "PRODSIN": [...] }
22. ENDPOINT: /api_consulta_estado_servicios
- URL: /api_consulta_estado_servicios
- Método: GET
- Autenticación: Requiere Token
- Descripción: Consulta estado de los servicios de facturación.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "DESCRIPCION": "...", "CODIGO": 730/731 }
23. ENDPOINT: /api_reprocesar_factura
- URL: /api_reprocesar_factura
- Método: POST
- Autenticación: Requiere Token
- Descripción: Reprocesa y regulariza una factura (genera nuevo XML y CUF si es necesario).
- Estructura JSON Request:
{ "cliente": {"nit": "string",
"cuf": "string"
}
}
- Respuestas Exitosas:
- 200 OK: { "TRANSACCION": true, "DESCRIPCION": "REGULARIZACIÓN EXITOSA", "nuevo_cuf": "...", "url_qr": "...", "factura_xml_base64": "..." }
24. ENDPOINT: /ping
- URL: /ping
- Método: GET
- Autenticación: No requiere
- Descripción: Health check del servicio.
- Estructura JSON Request: N/A
- Respuestas Exitosas:
- 200 OK: JSON con información del sistema y timestamp.