Manual tecnico – WSSoapCfe

Guia para integradores del servicio SOAP de CFE. El modulo publica un servicio SOAP 1.2 estilo document/literal con autenticacion por encabezado propio y expone metodos para validar, firmar, consultar CFEs, asignar numeracion (CAE) y flujos POS.

Endpoints y contratos

Servicio: https://<host>/ws_cfe
WSDL: https://<host>/ws_cfe?wsdl
XSD: https://<host>/cfe/WSSoapCfe/wsdl/cfe_service.xsd
Namespaces: tns=http://bluetech.com.uy/ws/cfe, cfe=http://bluetech.com.uy/schemas/cfe
Version SOAP: 1.2 (soap12)

Autenticacion

Enviar el encabezado cfe:AuthHeader en cada solicitud:

<soap:Header xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:cfe="http://bluetech.com.uy/schemas/cfe">
  <cfe:AuthHeader>
    <cfe:Username>RUT_EMISOR</cfe:Username> <!-- rut de la empresa -->
    <cfe:Password>CLAVE_INBOX_WS</cfe:Password> <!-- campo Empresa.ClaveInboxWs -->
  </cfe:AuthHeader>
</soap:Header>

Si el header falta o la clave no coincide, el servidor responde SoapFault Client.Authentication.

Tipos base de respuesta

cfe:CfeResponse (CodRta, TipoMensaje, MensajeRta y contexto del CFE: RutEmisor, CodComercio, CodTerminal, TipoCfe, Serie, NumeroCfe, Uuid, XmlCfeFirmado, CodigoSeguridad, DatosQr, ImagenQr, FechaFirma, Adenda, Etiquetas, EstadoSituacion, EstadoEnDgiCfeRecibido, IdReq, IdCae, CaeNroDesde, CaeNroHasta, VencimientoCae, RangoDesde, RangoHasta, FechaReq, HoraReq, Certificado, CertificadoParaFirmarCfe, ClaveCertificadoFirma).
cfe:SolicitudFirmaCfeResponse (UUID, TipoCfe, Serie, Numero, CodigoRespuesta, MensajeRespuesta, CodigoTerminal, CodigoComercio, NumeroInicialCAE, NumeroFinalCAE, VencimientoCAE, CFEFirmado, DatosCodigoQr, CodigoSeguridad, FechaFirmaCFE, ImagenQr).
cfe:PosResponse (CodResult, IdTransaccion, Result, Message, ProviderData JSON).
Errores tipicos: CodRta 0/00 = OK, 422/31/30 = errores de validacion, 404/01 = no encontrado o rechazado, 409 = conflicto, 500/96 = error interno.

Operaciones principales de CFE

SolicitarFirmaCfe

Valida, firma y registra un CFE que llega sin firma.

Request (cfe:SolicitarFirmaCfeRequest): RutEmisor, TipoCfe (int), Uuid, XmlCfe (string XML), CodComercio, CodTerminal, Adenda (opcional), EmailEnvioPdf (opcional; coma/punto y coma), DestinoImpresion (opcional, cola para imprimir).
Response (cfe:SolicitudFirmaCfeResponse): CodigoRespuesta 00 si el CFE fue aceptado y firmado; incluye Serie/Numero asignados, XML firmado en CFEFirmado, CodigoSeguridad/QR, datos de CAE y FechaFirmaCFE. Codigos 31 (formato), 30 (datos), 01 (rechazado) o 96 (error).
Ejemplo:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:cfe="http://bluetech.com.uy/schemas/cfe">
  <soap:Header>...AuthHeader...</soap:Header>
  <soap:Body>
    <cfe:SolicitarFirmaCfeRequest>
      <cfe:RutEmisor>20123456789</cfe:RutEmisor>
      <cfe:TipoCfe>111</cfe:TipoCfe>
      <cfe:Uuid>e3c2...</cfe:Uuid>
      <cfe:XmlCfe><![CDATA[<CFE>...</CFE>]]></cfe:XmlCfe>
      <cfe:CodComercio>001</cfe:CodComercio>
      <cfe:CodTerminal>POS1</cfe:CodTerminal>
      <cfe:EmailEnvioPdf>[email protected];[email protected]</cfe:EmailEnvioPdf>
    </cfe:SolicitarFirmaCfeRequest>
  </soap:Body>
</soap:Envelope>

EnviarCfeFirmado

Registra un CFE ya firmado por el integrador.

Request (cfe:EnviarCfeFirmadoRequest): RutEmisor, TipoCfe, XmlCfeFirmado, Uuid (opcional), Adenda (opcional), CodComercio/CodTerminal (opcional), EmailEnvioPdf (opcional).
Response (cfe:CfeResponse): CodRta 0 si OK, incluye Serie/Numero, XmlCfeFirmado, CodigoSeguridad, DatosQr, info de CAE y FechaFirma.
Validaciones: firma digital y estructura (CfeService::validarCFE), chequeo de duplicados (TipoCfe/Serie/Numero).

ValidarCfe

Chequea estructura de un XML (firmado o no).

Request: RutEmisor, XmlCfe, Firmado (bool, opcional).
Response: CodRta 0 si valido, junto con TipoCfe, Serie, NumeroCfe, RutEmisor y Uuid detectados.

ConsultarEstadoCfe

Busca un CFE ya emitido.

Request: RutEmisor y EITHER Uuid OR (TipoCfe + Serie + NumeroCfe). CodComercio/CodTerminal opcionales.
Response: CodRta 0 si se encuentra. Incluye XmlCfeFirmado, DatosQr, CodigoSeguridad, Adenda, FechaFirma, EstadoSituacion (ANULADO, RECHAZADO_DGI, OBSERVADO_DGI, PENDIENTE_ENVIO, EMITIDO) y EstadoEnDgiCfeRecibido (ACEPTADO/OBSERVADO/RECHAZADO).

SolicitarRangoCae

Reserva numeracion para un terminal.

Request: RutEmisor, TipoCfe, CodComercio, CodTerminal, FechaSolicitud (opcional, default ahora).
Response: CodRta 0 con Serie, RangoDesde/Hasta, IdCae, CaeNroDesde/Hasta y VencimientoCae. CodRta 409 si no pudo reservar.

ConsultaSiguienteNumero

Retorna la Serie y el siguiente numero disponible segun CAE vigente.

Request: RutEmisor, CodComercio, CodTerminal, TipoCfe.
Response: CodigoRespuesta 00 con Serie y SiguienteNumero, o 01 si no hay numeracion.

PDF

EnviarCfePdf: encola el envio por correo. Request: RutEmisor, TipoCfe, Serie, Numero, Emails (lista separada), Formato opcional. Respuesta CodigoRespuesta 00 si se encolo.
ObtenerPdfCfe: devuelve el PDF base64 (PdfBytes). Request: RutEmisor, TipoCfe, Serie, Numero, Formato opcional (default Estandar). Codigos 00 OK, 01 no encontrado, 96 error.

Consultas auxiliares

ConsultaCae: RutEmisor, TipoCfe, Serie, Numero. Devuelve NumeroAutorizacion, rango y fechas del CAE si existe (CodigoRespuesta 00) o 01 si no.
ConsultaRutWebService: RutEmisor, RUT (a consultar), IdCertificado opcional. Responde CodigoRespuesta 00 con Datos JSON de DGI.
EchoWebService: reflejo de Mensaje (util para smoke test).

Operaciones POS

PosEnviarVenta: registra venta POS para conciliacion. Campos: RutEmisor, IdPuntoEmision, IdComprobante, FacturaConsumidorFinal (bool opc), FacturaMonto, FacturaMontoGravado/IVA (opc), FacturaNro (opc), TipoMoneda (opc), MontoTransaccion, ProveedorPos. Respuesta PosResponse con CodResult (0 = OK).
PosEnviarDevolucion: requiere IdComprobante original a devolver e IdComprobanteDevolver, FacturaNro (opc), ProveedorPos. Valida que la transaccion original pertenezca a la empresa y genere ticket de referencia.
PosConsultarEstado: RutEmisor, IdTransaccion. Solo cuando el estado interno es CONSULTAR_ESTADO.
PosCancelarTransaccion: RutEmisor, IdTransaccion; cambia a estado CANCELAR_TRANSACCION.
ProviderData en la respuesta es JSON normalizado del adquirente (campo RawDataProvider/ProviderData/Data segun plugin).

Buenas practicas

Usar siempre SOAP 1.2 y Content-Type: application/soap+xml; charset=utf-8.
Enviar XML del CFE como string (no base64) y opcionalmente dentro de CDATA para evitar escapado.
Uuid es obligatorio en SolicitarFirmaCfe; en EnviarCfeFirmado es opcional pero ayuda a trazabilidad y consultas.
Manejar Codigos/CodRta distintos de 0/00 como error de negocio (no solo HTTP 200).
EmailEnvioPdf acepta array SOAP, coma o punto y coma; se filtraran direcciones vacias.
DestinoImpresion en SolicitarFirmaCfe agrega un job en CfePrintJob si el CFE se registra.

Integración mediante servicio SOAP