Web Service - INSIGNA · 2018-11-02 · El Web Service de INSIGNA es un servicio basado en SOAP que...

Página | 1

Web Service

INSIGNA

Página | 2

Contenido

Contenido ................................................................................................................................. 2

1. Introducción ...................................................................................................................... 5

1.1. Tipos de CFDI ................................................................................................................ 5

2. Funcionalidad del Web Service ............................................................................................ 5

2.1. Autenticación ................................................................................................................. 6

2.1.1. Respuestas con mensajes de error ............................................................................... 6

2.1.2. Estructura de una excepción ........................................................................................ 6

2.2. Timbrado de CFDI .......................................................................................................... 7

2.2.1. Datos de entrada ........................................................................................................ 8

2.2.2. Estructura de petición SOAP ........................................................................................ 8

2.2.3. Datos de respuesta ..................................................................................................... 8

2.2.4. Estructura de respuesta SOAP ..................................................................................... 9

2.2.5. Códigos de respuesta .................................................................................................. 9

2.2.5.1. Códigos de éxito...................................................................................................... 9

2.2.5.2. Códigos de error ................................................................................................... 10

2.3. Verificación de Timbrado ............................................................................................... 10

2.3.1. Datos de entrada ...................................................................................................... 10

2.3.2. Estructura de petición SOAP ...................................................................................... 11

2.3.3. Datos de respuesta ................................................................................................... 11

2.3.4. Estructura de respuesta SOAP ................................................................................... 12

2.3.5. Códigos de respuesta ................................................................................................ 12

2.3.5.1. Códigos de éxito.................................................................................................... 12

2.3.5.2. Códigos de error ................................................................................................... 12

2.4. Cancelación de CFDI ..................................................................................................... 13

2.4.1. Proceso de Cancelación ............................................................................................. 13

2.4.2. Datos de entrada ...................................................................................................... 14





Página | 3

2.4.6.1. Códigos de éxito.................................................................................................... 17

2.4.6.2. Códigos de error ................................................................................................... 17

2.5. Validación de CFDI ....................................................................................................... 18

2.5.1. Datos de entrada ...................................................................................................... 18





2.5.5.1. Códigos de éxito.................................................................................................... 20

2.5.5.2. Códigos de error ................................................................................................... 20

2.6. Consulta de CFDI .......................................................................................................... 20

2.6.1. Datos de entrada ...................................................................................................... 21





2.6.5.1. Códigos de éxito.................................................................................................... 22

2.6.5.2. Códigos de error ................................................................................................... 22

2.7. Validación de certificado de sello digital ......................................................................... 23

2.7.1. Datos de entrada ...................................................................................................... 23





2.7.5.1. Códigos de éxito.................................................................................................... 24

2.7.5.2. Códigos de error ................................................................................................... 24

2.8. Validación de RFC ......................................................................................................... 25

2.8.1. Datos de entrada ...................................................................................................... 25





2.8.5.1. Códigos de éxito.................................................................................................... 27

2.8.5.2. Códigos de error ................................................................................................... 27

Página | 4

2.9. Consulta de estatus de CFDI ......................................................................................... 27

2.9.1. Datos de entrada ...................................................................................................... 27





2.9.5.1. Códigos de éxito.................................................................................................... 29

2.9.5.2. Códigos de error ................................................................................................... 29

3. Códigos de Respuesta ...................................................................................................... 30

3.1. Códigos de respuesta definidos por el SAT ..................................................................... 30

3.2. Códigos de respuesta definidos por el Web Service ......................................................... 32

4. Ejemplos de implementación ............................................................................................. 35

4.1. JAVA ............................................................................................................................ 35

4.1.1. Asunciones y dependencias ....................................................................................... 35

4.1.2. Generación de clases del Web Service ........................................................................ 35

4.1.3. Cliente ejemplo ......................................................................................................... 37

4.2. .NET ............................................................................................................................ 41


4.2.2. Referencia del Web service ........................................................................................ 42

4.2.3. Configuración de la conexión ..................................................................................... 43

4.2.4. Cliente ejemplo en C# ............................................................................................... 45

4.2.5. Cliente ejemplo en Visual Basic .................................................................................. 47

4.3. DELPHI ........................................................................................................................ 48


4.3.2. Unidad InsignaWs ..................................................................................................... 48

4.3.3. Unidad WSSecurity .................................................................................................... 51

4.3.4. Unidad Client ............................................................................................................ 56

4.3.5. Cliente ejemplo ......................................................................................................... 60

4.4. Python ......................................................................................................................... 62


4.4.1.1. Librería Suds ......................................................................................................... 62

4.4.2. WsSecurity ............................................................................................................... 63

4.4.3. Cliente ejemplo ......................................................................................................... 64

4.5. PHP ............................................................................................................................. 65

Página | 5


4.5.2. Cliente Ejemplo ......................................................................................................... 66

4.5.2.1. Clase InsignaClient ................................................................................................ 66

4.5.2.2. Clase CfdiInfoWrapper ........................................................................................... 69

4.5.2.3. Consulta de cfdi utilizando la clase CfdiInfoWrapper ................................................ 71

1. Introducción

El Web Service de INSIGNA es un servicio basado en SOAP que le permitirá timbrar, cancelar y

validar facturas electrónicas vía internet desde su sistema corporativo.

El servicio es gratuito y fácil de implementar.

1.1. Tipos de CFDI

En el protocolo INSIGNA se identifica como un CFDI a los siguientes tipos de comprobantes:

Comprobante Fiscal Digital por Internet (CFDI V3.2 y CFDI V3.3)

Documento Electrónico de Retenciones e información de Pagos (Retención Pago V1.0) Por lo que al hacer referencia a un CFDI dentro de este manual tomaremos en cuenta los comprobantes previamente mencionados.

2. Funcionalidad del Web Service

A continuación se describen las funciones del Web Service de INSIGNA:

Servicio Método Descripción

Timbrado de CFDI signCFDI Valida, sella (de ser requerido) y timbra un CFDI

Verificación de

Timbrado

verifyOperation Consulta el estatus final de una petición de

timbrado mediante el Web Service

Cancelación de

CFDI

cancelCFDI Cancela un CFDI timbrado

Validación de CFDI

validateCFDI Verifica la validez de un CFDI timbrado

Consulta de CFDI getCfdiInfo Consulta el estatus actual de un CFDI timbrado o importado en el sistema de INSIGNA

Validación de

certificado

validateCertificateRFC Verifica la vigencia de un certificado de sello

digital

Validación de RFC validateLRFC Verifica si un RFC se encuentra en la lista de RFCs

inscritos no cancelados (LRFC) del SAT

Estatus del Cfdi getCfdiStatus Verifica el estatus de un CFDI en el sistema del SAT

Página | 6

2.1. Autenticación

Para conectarse al Web Service de INSIGNA es necesario proporcionar el usuario y contraseña que

utiliza para ingresar a INSIGNA. La autenticación se realiza mediante el uso de un

“WSSecurityHeader”, el cual incluye un “UsernameToken” con los datos de autenticación del

usuario.

<soap:Header xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<wsse:UsernameToken> <wsse:Username>username</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>

</wsse:UsernameToken> </wsse:Security>

</soap:Header> Figura 1 - Ejemplo de WSSecurityHeader de una petición SOAP.

2.1.1. Respuestas con mensajes de error

En algunas situaciones, el WebService de INSIGNA puede regresar una respuesta que describe

excepciones en la comunicación con el cliente. Este tipo de respuesta está formada por un objeto OperationFailed. Los atributos del objeto OperationFault se describen a continuación:

Parámetro Tipo Descripción

errorCode int Código de error

errorDescription String Descripción del error

serverTransactionId String Identificador de la transacción proporcionado por el servidor de la aplicación

transactionId String Identificador de la transacción ingresado por el usuario

requestDate Date Fecha de petición al servidor

responseDate Date Fecha de respuesta del servidor

executionTime long Tiempo de ejecución del comando (en milisegundos)

2.1.2. Estructura de una excepción

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Body>

<soap:Fault> <soap:Code> </soap:Code>

<soap:Reason> </soap:Reason> <soap:Detail>

Página | 7

<OperationFailed xmlns =“http://ws.certipass.mx/”> <errorCode></errorCode>

<errorDescription></errorDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate>

<executionTime></ executionTime> </OperationFailed > </soap:Detail>

</soap:Fault> </soap:Body>

</soap:Envelope> Figura 2 - Ejemplo de la estructura de una excepción

2.2. Timbrado de CFDI

El método signCfdi se usa para timbrar un CFDI. Si la factura no cuenta con el sello, el servicio se

encargará de generarlo.

Importante

Si desea que el Web Service genere el sello de la factura, antes deberá registrar el RFC emisor en

https://www.insigna.mx/

El sistema le solicitará su llave privada, el certificado (archivos .key y .cer) y la contraseña de la llave

privada.

Si enviará los XML con el sello, no es necesario registrar el RFC en INSIGNA.


Página | 8

2.2.1. Datos de entrada

Los atributos del objeto de entrada CfdiSignWrapper son los siguientes:

Parámetro Tipo Requerido/Opcional Descripción

cfdi String Requerido XML del CFDI, codificado en Base64

transactionId String Opcional Identificador de transacción de timbrado

2.2.2. Estructura de petición SOAP

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header><wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:UsernameToken><wsse:Username></wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password> <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce> <wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:signCfdi> <ws:cfdiSignWrapper> <ws:cfdi></ws:cfdi> <ws:transactionId></ws:transactionId> </ws:cfdiSignWrapper> </ws:signCfdi> </soap:Body> </soap:Envelope>

Figura 3 - Estructura de petición SOAP Servicio de timbrado

2.2.3. Datos de respuesta

Los atributos del objeto de respuesta SignCfdiResponse son los siguientes:

Nombre de la propiedad

Tipo Descripción

responseCode int Código de respuesta del timbrado

responseDescription String Descripción de la respuesta

serverTransactionId String Identificador de la transacción proporcionado por el servidor

de la aplicación


Página | 9




signedXml String XML del CFDI timbrado, codificado en Base64

uuid String UUID del CFDI timbrado

2.2.4. Estructura de respuesta SOAP


<signCfdiResponse xmlns="http://ws.certipass.mx/"> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></transactionId> <serverTransactionId></serverTransactionId> <requestDate></requestDate> <responseDate></responseDate> <executionTime></executionTime> <signedXml></signedXml> <uuid></uuid>

</return> </signCfdiResponse>

</soap:Body> </soap:Envelope>

Figura 4 - Estructura de respuesta SOAP Servicio de timbrado

2.2.5. Códigos de respuesta

A continuación se mencionan los posibles códigos de respuesta del comando signCfdi. Si requiere

más información, favor de consultar la sección de códigos de respuesta.

2.2.5.1. Códigos de éxito

A continuación se enlistan los códigos de éxito para el comando signCfdi:

1000

Página | 10

2.2.5.2. Códigos de error

A continuación se enlistan los códigos de error para el comando signCfdi:

301

302

303

304

305

306

307

308

401

402

403

2010

2309

2600

2601

2602

2603

4100

4200

4210

4211

4212

4213

4214

4215

4216

4217

4218

4219

4220

4222

4223

4224

4230

2.3. Verificación de Timbrado

Bajo algunas circunstancias (fallos de red, timeouts, etc.), es posible que no reciba la respuesta del

comando de timbrado. El método verifyOperation le permite recuperar un CFDI mediante su

cadena original o el identificador de transacción de timbrado.


Los atributos del objeto de entrada VerifyOperationWrapper son los siguientes:

Parámetro Tipo Requerido/

Opcional Descripción Observaciones

transactionId String Opcional Identificador de la transacción ingresada por

el usuario

signTransactionI

d String Opcional

Identificador utilizado en la transacción de timbrado a

verificar

Es requerido si no se incluye el atributo

originalChain

originalChain String Opcional Cadena original del CFDI,

codificada en Base64

Es requerido si no se incluye el atributo

signTransactionId

Página | 11


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password> <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce> <wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:verifyOperation> <ws:verifyOperationWrapper> <ws:originalChain></ws:originalChain> <ws:signTransactionId></ws:signTransactionId> <ws:transactionId></ws:transactionId> </ws:verifyOperationWrapper> </ws:verifyOperation> </soap:Body> </soap:Envelope>

Figura 5 - Estructura de petición SOAP Servicio de Verificación


Los atributos del objeto de respuesta VerifyOperationResponse son los siguientes:


responseCode int Código de respuesta de la verificación


serverTransactionId String Identificador de la transacción proporcionado por el

servidor de la aplicación





cfdi String XML del CFDI consultado, codificado en Base64

uuid String Folio fiscal de CFDI

cfdiStatus String Estatus del CFDI

Página | 12



<VerifyOperationResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate> <executionTime></ executionTime> <cfdi></cfdi> <uuid></uuid> <cfdiStatus></cfdiStatus>

</return> </VerifyOperationResponse>


Figura 6 - Estructura de respuesta SOAP Servicio de Verificación


A continuación se mencionan los posibles códigos de respuesta del comando verifyOperation. Si

requiere más información, favor de consultar la sección de códigos de respuesta.


A continuación se enlistan los códigos de éxito para el comando verifyOperation:

1000


A continuación se enlistan los códigos de error para el comando verifyOperation:

205

2700

4200

4210

4211

4212

4213

4214

4215

4216

4217

4218

4219

4220

4230

4231

Página | 13

2.4. Cancelación de CFDI

El método cancelCfdi se usa para cancelar un CFDI timbrado previamente.

2.4.1. Proceso de Cancelación

El proceso de cancelación se aplicara a todos los CFDIs excepto a los que tengan alguna de estas

características:

CFDI que aparen ingresos hasta $5,000.00

Nómina

Egreso

Traslado

Emitido desde el portal web del SAT “Mis Cuentas”

CFDI de retenciones e información de pagos

CFDI de Ingreso expedidos a contribuyentes el RIF

Dentro de los tres días siguientes a la emisión

Operaciones con público en general

Recibidos por residentes en el extranjero

CFDI a través del adquiriente y sector primario

CFDI emitido por integrantes del Sistema Financiero

Aviso

Ya es posible cancelar CFDIs que no fueron timbrados por medio de INSIGNA, para ello es necesario

enviar el certificado del RFC emisor como se muestra en la siguiente sección. Los CFDIs externos

que se cancelan consumen un timbre.

Importante

Si desea que el Web Service genere el signatureValue, antes deberá registrar el RFC emisor en

https://www.insigna.mx/. El sistema le solicitará su llave privada, el certificado (archivos .key y .cer)

y la contraseña de la llave privada.

Si su sistema calculará y enviará el signatureValue, no es necesario registrar el RFC en INSIGNA para

cancelar sus facturas.


Página | 14


Los atributos del objeto de entrada CfdiCancelWrapper son los siguientes:


uuid String Requerido Folio fiscal del CFDI previamente timbrado

signatureValue String Opcional

Atributo requerido solo si no se

registrado el RFC emisor en https://www.insigna.mx/; de lo

contrario la firma es requerida para cancelar el CFDI codificada en

Base64; se obtiene con el RFC del

emisor, el UUID del CFDI, la fecha de cancelación, el certificado y la

llave privada del emisor


Página | 15

cancelationDate Date Requerido Fecha de cancelación del CFDI

certificate String Opcional

Atributo requerido solo si se quiere cancelar un CFDI que no fue

timbrado por medio de INSIGNA, el

certificado debe venir codificado en Base64. Aún cuando el certificado se

encuentre registrado en https://www.insigna.mx/ es

necesario enviarlo

transactionId String Opcional Identificador de la transacción ingresado por el usuario

cfdiTotal BigDecimal Opcional

Atributo requerido solo si se cancela

un CFDI externo. Monto total del CFDI

cfdiType String Opcional

Atributo requerido solo si se cancela

un CFDI externo. Identificador del

tipo del comprobante CFDI [I (Ingreso), E (Egreso), N (Nomina), T

(Traslado), P (Pagos)]

cfdiReceptiorRfc String Opcional Atributo requerido solo si se cancela un CFDI externo. EL RFC del

receptor del CFDI


Página | 16


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password><wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce><wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:cancelCfdi> <ws:cfdiCancelWrapper> <ws:uuid></ws:uuid> <ws:signatureValue></ws:signatureValue> <ws:cancelationDate></ws:cancelationDate> <ws:certificate></ws:certificate> <ws:transactionId></ws:transactionId> <ws:cfdiTotal></ws: cfdiTotal> <ws:cfdiType></ws:cfdiType> <ws:cfdiReceptorRfc></ws: cfdiReceptorRfc> </ws:cfdiCancelWrapper> </ws:cancelCfdi> </soap:Body> </soap:Envelope>

Figura 7 - Estructura de petición SOAP Servicio de cancelación


Los atributos del objeto de salida CancelCfdiResponse son los siguientes:


responseCode Intenger Código de respuesta de la cancelación


serverTransactionId String Identificador de la transacción proporcionado por el servidor de la aplicación.

transactionId String Identificador de la transacción ingresado por el usuario.

requestDate Date Fecha de petición al servidor.

responseDate Date Fecha de respuesta del servidor.

executionTime Long Tiempo de ejecución del comando (en milisegundos).

receipt String Acuse de cancelación del SAT, codificado en Base64

Página | 17



<CancelCfdiResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate> <executionTime></ executionTime> <receipt></receipt>

</return> </CancelCfdiResponse>


Figura 8 - Estructura de respuesta SOAP Servicio de cancelación


A continuación se mencionan los posibles códigos de respuesta del comando cancelCfdi. Si



A continuación se enlistan los códigos de éxito para el comando cancelCfdi:

201

202

250*

*Cuando se reciba un código de éxito 250 para obtener el acuse de recibo sera necesario saber el estatus en el que se encuentra la cancelación, para ello se dan dos opciones:

1. Configurar el servicio de Notificaciones de estatus de cancelación en https://www.insigna.mx/, la cual se encuentra en la sección Mi Cuenta > Configuración Adicional en el cual se deberá ingresar el correo en el cual se desea recibir las notificaciones del cambio de estatus y seleccionar el checkbox para activar el servicio.

2. Usar el comando de Consulta de estatus de CFDI el cual regresara el estatus actual del CFDI.

Cuando el estatus de la cancelación pase a Cancelación aceptada o Cancelación por vencimiento se

deberá enviar otra vez el comando de cancelación el cual ahora regresara un código 201 o 202 y el cual

tendrá en el recibo de cancelación.


A continuación se enlistan los códigos de error para el comando cancelCfdi:

203 204

205

206 251

252

253 301

302


Página | 18

303 304

305

1201

1202

1203

1205

1300

1301

1302

1303

1304 1305

1306

1307

1308

1309

4200

4210

4211

4212

4213

4214 4215

4216

4217

4218

4219

4220

4221

4230

4232

2.5. Validación de CFDI

El método validateCfdi se usa para verificar la validez de un CFDI timbrado, incluso si no fue

timbrado por medio de INSIGNA. La validación de CFDI consume un timbre.


Los atributos del objeto de entrada ValidateCfdiWrapper son los siguientes:


cfdi String Requerido XML del CFDI a validar, codificado en Base64

transactionId String Opcional Identificador de transacción de la validación

Página | 19


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password><wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce><wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:validateCfdi> <ws:validateCfdiWrapper> <ws:cfdi></ws:cfdi> <ws:transactionId></ws:transactionId> </ws:validateCfdiWrapper> </ws:validateCfdi> </soap:Body> </soap:Envelope>

Figura 9 - Estructura de petición SOAP Servicio de validación


Los atributos del objeto de salida ValidateCfdiResponse son los siguientes:


responseCode int Código de respuesta de la validación



transactionId String Identificador de la transacción ingresado por el usuario.






<validateCfdiResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate>

Página | 20

<responseDate></ responseDate> <executionTime></ executionTime>

</return> </validateCfdiResponse>


Figura 10 - Estructura de respuesta SOAP Servicio de validación


A continuación se mencionan los posibles códigos de respuesta del comando validateCfdi. Si



A continuación se enlistan los códigos de éxito para el comando validateCfdi:

1000


A continuación se enlistan los códigos de error para el comando validateCfdi:

301

302

303

304

305

401

402

403

601

602

1002

2010

2309

2600

2601

2602

2603

2604

2800

4200

4210

4211

4212

4213

4214

4215

4216

4217

4218

4219

4220

4230

2.6. Consulta de CFDI

El método getCfdiInfo se usa para consultar el estatus de un CFDI timbrado o importado en el

sistema de INSIGNA.

Página | 21


Los atributos del objeto de entrada CfdiInfoWrapper son los siguientes:



transactionId String Opcional Identificador de transacción de

consulta


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password><wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce><wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:getCfdiInfo> <ws:cfdiInfoWrapper> <ws:uuid></ws:uuid> <ws:transactionId></ws:transactionId> </ws:cfdiInfoWrapper> </ws:getCfdiInfo> </soap:Body> </soap:Envelope>

Figura 11 - Estructura de petición SOAP Servicio de Consulta


Los atributos del objeto de respuesta GetCfdiInfoResponse son los siguientes:


responseCode int Código de respuesta de la consulta







Página | 22

cfdi String XML del CFDI consultado, codificado en Base64

uuid String Folio fiscal de CFDI consultado

cfdiStatus String Estatus del CFDI consultado



<getCfdiInfoResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate> <executionTime></ executionTime> <uuid></uuid> <cfdiStatus></cfdiStatus> <cfdi></cfdi>

</return> </getCfdiInfoResponse>


Figura 12 - Estructura de respuesta SOAP Servicio de Consulta


A continuación se mencionan los posibles códigos de respuesta del comando getCfdiInfo. Si



A continuación se enlistan los códigos de éxito para el comando getCfdiInfo:

1000


A continuación se enlistan los códigos de error para el comando getCfdiInfo:

205

4200

4210

4211

4212

4213

4214

4215

4216

4217

4218

4219

4220

4230

Página | 23

2.7. Validación de certificado de sello digital

El método validateCertificateRFC se usa para verificar la vigencia y/o el estatus de un certificado

de sello digital para un RFC que se encuentre registrado en el LCO (Lista de Contribuyentes con

obligación).


Los atributos del objeto de entrada ValidateCertificateRFCWrapper son los siguientes:


rfc String Requerido RFC asociado al certificado

serie String Requerido Número de serie del certificado de sello digital

transactionId String Opcional Identificador de transacción


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password><wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce><wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:validateCertificateRFC> <ws:validateCertificateRFCWrapper> <ws:rfc></ws:rfc> <ws:serie></ws:serie> <ws:transactionId></ws:transactionId> </ws:validateCertificateRFCWrapper> </ws:validateCertificateRFC> </soap:Body> </soap:Envelope>

Figura 13 - Estructura de petición SOAP servicio de validación de certificado de sello digital


Los atributos del objeto de respuesta ValidateCertificateRFCResponse son los siguientes:

Página | 24










csdFinalDate String Fecha de vencimiento del certificado

csdState String El estado del certificado en la LCO del SAT



<validateCertificateRFCResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate> <executionTime></ executionTime> <csdFinalDate></csdFinalDate> <csdState></csdState>

</return> </validateCertificateRFCResponse>


Figura 14 - Estructura de respuesta SOAP servicio de validación de certificado de sello digital


A continuación se mencionan los posibles códigos de respuesta del comando

validateCertificateRFC. Si requiere más información, favor de consultar la sección de códigos de

respuesta.


A continuación se enlistan los códigos de éxito para el comando validateCertificateRFC:

1000


A continuación se enlistan los códigos de error para el comando getCfdiInfo:

Página | 25

2901 2902

4200

4210

4211

4212

4213

4214 4215

4216

4217

4218

4220

4230

2.8. Validación de RFC

El método validateLRFC se usa para verificar si un RFC se encuentra en la lista de RFCs inscritos

no cancelados (LRFC) del SAT.


Los atributos del objeto de entrada ValidateLRFCWrapper son los siguientes:


rfc String Requerido RFC a buscar

transactionId String Opcional Identificador de transacción


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password><wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce><wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:validateLRFC> <ws:validateLRFCWrapper> <ws:rfc></ws:rfc> <ws:transactionId></ws:transactionId> </ws:validateLRFCWrapper> </ws:validateLRFC> </soap:Body> </soap:Envelope>

Figura 15 - Estructura de petición SOAP servicio de validación de RFC

Página | 26


Los atributos del objeto de respuesta ValidateLRFCResponse son los siguientes:









sncf String Determina si es una entidad adherida al Sistema Nacional de Coordinación Fiscal

outsourcing String Indica si el régimen es Subcontratación



<validateLRFCResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate> <executionTime></ executionTime> <sncf></sncf> <outsourcing></outsourcing>

</return> </validateLRFCResponse>


Figura 16 - Estructura de respuesta SOAP servicio de validación de RFC


A continuación se mencionan los posibles códigos de respuesta del comando validateLRFC. Si


Página | 27


A continuación se enlistan los códigos de éxito para el comando validateLRFC:

1000


A continuación se enlistan los códigos de error para el comando validateLRFC:

2910

4200

4210

4211

4212

4213

4214

4215

4216

4217

4218

4220

4230

2.9. Consulta de estatus de CFDI

El método getCfdiStatus se usa para consultar el estatus de un CFDI en el sistema del SAT.


Los atributos del objeto de entrada CfdiStatusWrapper son los siguientes:



issuerRFC String Requerido El rfc del emisor

receptorRfc Sting Requerido El rfc del receptor

cfdiTital BigDecimal Requerido Monto total del CFDI

transactionId String Opcional Identificador de la transacción ingresado por el usuario.

Importante

El método getCfdiStatus es el medio principal para conocer cuando el estatus de un CFDI que se ha

mandado a cancelar ha cambiado a Cancelado (Cancelación Aceptada) o Vigente (Cancelación

Rechazada).

Página | 28


<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ws="http://ws.certipass.mx/"> <soap:Header> <wsse:Security soap:mustUnderstand="true" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"><wsse:UsernameToken><wsse:Username></wsse:Username><wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText"></wsse:Password><wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"></wsse:Nonce><wsu:Created></wsu:Created></wsse:UsernameToken></wsse:Security> </soap:Header> <soap:Body> <ws:getCfdiStatus> <ws:cfdiStatusWrapper> <ws:uuid></ws:uuid> <ws:issuerRFC></ws:issuerRFC> <ws:receptorRFC></ws:receptorRFC> <ws:cfdiTotal></ws:cfdiTotal> <ws:transactionId></ws:transactionId> </ws:cfdiInfoWrapper> </ws:getCfdiInfo> </soap:Body> </soap:Envelope>

Figura 17 - Estructura de petición SOAP Servicio de Consulta


Los atributos del objeto de respuesta CfdiStatusResult son los siguientes:


responseCode Intenger Código de respuesta de la consulta







executionTime Long Tiempo de ejecución del comando (en milisegundos)

cfdiStatus String Estatus actual del CFDI (Vigente, Cancelado)

cancelationType String Tipo de cancelación posible en el CFDI (No cancelable, Cancelación con aceptación o Cancelación sin aceptación)

cancelationStatus String

Estatus de la cancelación (En proceso, Cancelación tiempo

vencido, Cancelación Aceptada, Rechazada, Cancelación sin aceptación)

Página | 29



<getCfdiStatusResponse xmlns=“http://ws.certipass.mx/”> <return>

<responseCode></responseCode> <responseDescription></responseDescription> <transactionId></ transactionId> <serverTransactionId></ serverTransactionId> <requestDate></ requestDate> <responseDate></ responseDate> <executionTime></ executionTime> <cfdiStatus></cfdiStatus> <cancelationType></cancelationType> <cancelationStatus></cancelationStatus>

</return> </getCfdiInfoResponse>


Figura 18 - Estructura de respuesta SOAP Servicio de Consulta


A continuación se mencionan los posibles códigos de respuesta del comando getCfdiStatus. Si



A continuación se enlistan los códigos de éxito para el comando getCfdiStatus:

1000


A continuación se enlistan los códigos de error para el comando getCfdiStatus:

601

602

2500

Página | 30

3. Códigos de Respuesta

3.1. Códigos de respuesta definidos por el SAT

Código Mensaje Descripción

201 UUID Cancelado exitosamente Cuando se puede cancelar correctamente un CFDI V3.2 o CFDI V3.3 con el UUID ingresado

202 UUID Previamente cancelado Cuando se intenta cancelar un CFDI V3.2 o

CFDI V3.3 y ya ha sido cancelado previamente

203

UUID No corresponde el RFC del

emisor y de quien solicita la cancelación

Cuando se intenta cancelar un CFDI V3.2 o

CFDI V3.3 y el RFC emisor es diferente al RFC que intenta cancelar

204 UUID No aplicable para cancelación

Cuando se intenta cancelar un CFDI V3.2 o

CFDI V3.3 y este no es cancelable por debido a estipulaciones del SAT

205 UUID No existe

Cuando se trata de consultar, verificar o

cancelar un CFDI V3.2 o CFDI V3.3 con un UUID que no existe

206 UUID no corresponde a un CFDI del

Sector Primario

Cuando se trata de cancelar un CFDI que no pertenece al sector primario

250

Factura en proceso de cancelación

La solicitud de cancelación de factura esta realizada y esta pendiente la aceptación de

esta por el receptor.

251

Solicitud de cancelación rechazada

La solicitud de cancelación de la factura ha sido rechazada por el receptor (El estatus es

vigente)

252 Factura no cancelable

Por regulaciones no es posible cancelar esta

factura

253 Error al cancelar la factura

Error interno al momento de cancelar la factura

301 XML mal formado Cuando el XML del CFDI V3.2 o CFDI V3.3 no

cumple con la estructura definida por el SAT

302 Sello mal formado o inválido El sello del emisor no es válido

303 Sello no corresponde a emisor El CSD del emisor no corresponde al RFC emisor del comprobante

304 Certificado revocado o caduco El CSD del emisor se encuentra revocado de

acuerdo a la lista LCO

305 La fecha de emisión no está dentro

de la vigencia del CSD del emisor

El CSD del emisor no está vigente para la fecha

de emisión del CFDI V3.2 o CFDI V3.3

306 El certificado no es de tipo CSD El certificado no tiene la estructura de uno de tipo CSD

307 El CFDI contiene un timbre previo El XML enviado a INSIGNA ya contiene un

timbre

Página | 31

308 Certificado no expedido por el SAT El CSD del emisor no fue firmado por un

Certificado de Autoridad del SAT

310 Uso de certificado de e.firma

inválido El certificado de sello digital esta incorrecto

401

La fecha de emisión se encuentra

en el futuro y fuera del rango de tolerancia (12 horas)

El rango entre la fecha de emisión y la fecha actual es mayor a 12 horas

El tiempo entra la fecha de emisión

y la fecha de firmado excede el

límite establecido (72 horas)

El rango entre la fecha de emisión y fecha de timbrado es mayor a 72 horas

402 RFC del emisor no se encuentra en el régimen de contribuyentes

El RFC del emisor no se encuentra en la lista LCO del SAT

403 La fecha de emisión no es posterior

al 01 de enero 2012

La fecha de emisión no es posterior al 01 de

enero 2012

601 La información para buscar el

comprobante no es válida

Cuando se consulta una factura por medio del

comando de Validación y alguno de los datos enviados es incorrecto

602 El comprobante no se encuentra en

el sistema del SAT

Cuando se consulta una factura por medio del

comando de Validación y no se encuentra en el SAT

1201 UUID Cancelado exitosamente Cuando se puede cancelar correctamente una Retención Pago V1.0 con el UUID ingresado

1202 UUID Previamente cancelado Cuando se intenta cancelar una Retención

Pago V1.0 y ya ha sido cancelado previamente

1203 UUID no corresponde con el emisor

Cuando se intenta cancelar una Retención

Pago V1.0 y el RFC emisor es diferente al RFC que intenta cancelar

1205 UUID No existe

Cuando se trata de consultar, verificar o

cancelar una Retención Pago V1.0 con un UUID que no existe

1300 Autenticación no válida Cuando el token de autenticación no es válido para el servicio de cancelación

1301 XML mal formado Cuando el XML de la Retención Pago V1. No cumple con la estructura definida por el SAT

1302 Estructura de folios no válida Cuando la estructura Folio que contiene los

UUID no es válida

1303 Estructura de RFC no válida Cuando la estructura en que se presenta el RFC del emisor no es válida

1304 Estructura de fecha no válida Cuando la estructura en que se presenta la fecha de expedición no es válida

1305 Certificado no corresponde al

emisor

Cuando el Certificado del emisor de la Retención Pago V1.0 no coincide con el

certificado con el cual fue firmado el CFDI

1306 Certificado no vigente El CSD del emisor no está vigente para la fecha

de emisión de la Retención Pago V1.0

Página | 32

1307 Uso de FIEL no permitido Cuando se intenta cancelar una Retención

Pago V1.0 utilizando una FIEL

1308 Certificado revocado o caduco El CSD del emisor se encuentra revocado de acuerdo a la lista LCO

1309 Firma mal formada o inválida El sello del emisor no es válido

3.2. Códigos de respuesta definidos por el Web Service

Los siguientes códigos son definidos por INSIGNA y pertenecen exclusivamente a su protocolo

de comunicación y reglas de negocio.

Código Mensaje Descripción

1000 Comando completado

exitosamente Respuesta a un comando exitoso

1002 El comprobante no se encuentra

en el sistema del SAT

El sistema del SAT no cuenta con el comprobante.

Le sugerimos intentar más tarde

2010 Error al validar la cantidad del parámetro

Cuando las cantidades utilizadas en el CFDI no

concuerdan, por ejemplo, la suma de los conceptos no es igual a la cantidad del subtotal 1

2309 Timbres no disponibles

Cuando el Servicio recibe un comando para

timbrar pero la cuenta no tiene timbres

disponibles

2500 Comando falló, servidor cerrando conexión.

Cuando hubo un error inesperado del lado del

servidor. En cancelaciones puede indicar fallas por

parte del servicio de cancelación del SAT

2600 Error en la estructura del

comprobante Cuando el xml del CFDI está mal formado

2601 RFC emisor no coincide con el

certificado emisor

Cuando el RFC del emisor del CFDI no coincide

con el certificado con el cual fue firmado el CFDI

2602 Fecha de expedición del comprobante no es válida

Cuando la fecha de expedición del CFDI no es válida

1 INSIGNA valida los totales y subtotales de acuerdo a lo especificado en el Anexo 20.

En un concepto o parte el valor unitario multiplicado por la cantidad no puede diferir del total

más de medio centavo. El subtotal de los nodos de impuestos o conceptos debe ser igual a la suma de cada

impuesto/concepto de dicho nodo. Se permite un margen de tolerancia de medio centavo

por cada impuesto/concepto del nodo. El total de la factura debe ser igual a la suma del subtotal menos los descuentos, menos los

impuestos retenidos y más los impuestos trasladados (ver Anexo 20, pag. 71). Se permite

un margen de tolerancia de medio centavo por cada impuesto/descuento.

Página | 33

2603 Error en la validación del sello de

la firma del comprobante

Cuando el certificado del emisor no está en la lista del LCO. Cuando el CFDI es inválido debido a que

fue modificado. Cuando hay problemas de

enconding

2604 Error en la validación del sello del

timbre del comprobante

Cuando el CFDI es inválido debido a que fue modificado, o no se encuentra timbrado

correctamente. Cuando hay problemas de enconding

2700 CFDI No encontrado

Cuando no se encuentra el CFDI correspondiente

al signTransactionId o a la cadena original ingresada

2800

No fue posible realizar la

validación del CFDI ante el SAT. Favor de intentar más tarde.

Cuando ocurre un error en la conexión al servicio

de validación del SAT o éste tiene una falla interna

2901 Certificado no encontrado El certificado de sello digital no fue encontrado en

la lista LCO

2902 El RFC no coincide con el certificado

El RFC proporcionado no coincide con el registrado en el certificado de sello digital

2910 El RFC no fue encontrado en la

lista

El RFC proporcionado no está registrado en la

lista LRFC del SAT al momento de la consulta

4100 No se encontró el certificado y la

llave privada para el RFC

Cuando se quiere timbrar un CFDI y no se tienen

los archivos para generar el sello

4200 Error interno al procesar el

comando

Cuando ocurre un error no esperado en la

ejecución de un comando

4210 El usuario o la contraseña no son

válidos. Favor de verificar

Cuando las credenciales que se envían para la

autenticación del usuario no corresponden a algún usuario de INSIGNA

4211

Los datos de autenticación están

incompletos. Por favor, verifique el usuario y la contraseña

Cuando no se envían completos los datos de autenticación del usuario

4212 La IP ha sido bloqueada Cuando el usuario intenta autenticarse 5 o más

veces sin éxito

4213 La IP no es válida Si por alguna razón no es posible detectar su dirección IP

4214 El usuario ha sido bloqueado Cuando el usuario intenta autenticarse 5 o más

veces sin éxito

4215 La petición SOAP contiene elementos no reconocidos

Cuando la petición SOAP contiene elementos que no están definidos dentro de la estructura del

Servicio web

4216 Error en el WSHeader Cuando el usuario envía elementos no reconocidos en el header de autenticación de la

petición SOAP

Página | 34

4217 El estatus del usuario no permite

el acceso:<Estatus>

Cuando un usuario que no se encuentra en Operación intenta acceder a los servicios del

Servicio Web de INSIGNA

4218 Se ha excedido el tamaño

máximo de texto

Cuando el usuario intenta enviar un elemento de

texto con un tamaño superior al definido como máximo en el sistema

4219 Error en la codificación base 64 de:<elemento>

Cuando el usuario envía un dato que no corresponde con una codificación en Base64

4220 Error en la estructura de la

petición SOAP

Cuando la petición SOAP tiene elementos no

válidos para su estructura

4221 La fecha de cancelación debe ser posterior a la fecha de emisión

del CFDI

Cuando se envía una fecha de cancelación anterior a la fecha de emisión del CFDI

4222 Archivo de certificado inválido Cuando el certificado del cliente no es válido

4223 Archivo de llave privada inválido Cuando la llave privada no es válida

4224

Ocurrió un error al parsear uno o

más de los parámetros de la

petición, favor de verificar.

El valor de uno o más parámetros del comando

están en un formato no válido y no pudo ser interpretado (error de conversión de tipos de

datos)

4225 Se ha excedido el máximo de

caracteres en la petición

Cuando el tamaño de la petición SOAP (número

de caracteres) supera el máximo permitido

4230

Por favor proporciona: <valor> Cuando no se ingresa un valor requerido.

Por favor verifica la escritura de: <valor>

Cuando el valor ingresado tiene errores de sintaxis.

Valor fuera de rango: <valor> Cuando el valor ingresado no está dentro del rango permitido.

Error en políticas: : <valor> Cuando el valor ingresado no cumple con alguna

regla de negocio.

La fecha no puede ser posterior a

la actual: <valor>

Cuando el valor de la fecha ingresada es anterior

a la actual y es requerido que sea posterior.

La fecha no puede ser anterior a

la actual: <valor>

Cuando el valor de la fecha ingresada es posterior

a la actual y es requerido que sea anterior.

<código de error>: <mensaje>

Cuando ocurre un error específico de alguna

matriz de validación publicada por el SAT (Complementos, CFDI V3.3, etc.)

Página | 35

4231

No se encontró una operación de

timbrado con el identificador de transacción proporcionado

Cuando el identificador de timbrado no ha sido utilizado previamente para identificar una

operación de timbrado o han transcurrido más de

72 horas desde que se utilizó

4232

Es necesario proporcionar el

certificado del RFC emisor en base 64 para poder realizar la

Cancelación de CFDI externo.

Cuando se intenta cancelar un CFDI que no fue

timbrado por INSIGNA, es necesario enviar el certificado público del RFC emisor en base 64

4. Ejemplos de implementación

El propósito de esta sección es explicar el proceso de creación de clientes en diferentes lenguajes

que consuman los servicios del Web Service de INSIGNA. El Web Service de INSIGNA se encuentra en la url https://ws.insigna.mx/services?wsdl, sin embargo los siguientes ejemplos de

implementación se conectan a nuestro ambiente de pruebas con la url https://beta.ws.insigna.mx/services?wsdl, usando las credenciales del usuario de pruebas público:

Url del Web Service: https://beta.ws.insigna.mx/services?wsdl

Usuario: usuariopruebas

Contraseña: ins1gN#4

4.1. JAVA

4.1.1. Asunciones y dependencias

Para iniciar el desarrollo del cliente es necesario contar con:

1. Archivo INSIGNAWS.wsdl (https://beta.ws.insigna.mx/services?wsdl) 2. Librería Apache CXF 3.1.12 (http://cxf.apache.org/)

El código completo de este cliente se encuentra en la siguiente liga: https://github.com/cops-

nic/insigna-webservice-java-client.

4.1.2. Generación de clases del Web Service

A continuación se describe como generar las clases del Web Service de INSIGNA usando la

herramienta Wsdl2Java de Apache CXF, es posible generar las clases del WSDL mediante otras

herramientas como wsdl2java de Apache Axis2 o wsimport de Java.

La generación de las clases se puede realizar desde línea de comandos o mediante código:

a) Mediante línea de comando

Ubicados en la carpeta “bin” del directorio de instalación de Apache CXF ingresamos el

siguiente comando:

wsdl2java -d rutaDelOutput rutaDelWsdl\INSIGNAWS.wsdl

https://ws.insigna.mx/services?wsdl

https://beta.ws.insigna.mx/services?wsdl


https://github.com/cops-nic/insigna-webservice-java-client

https://github.com/cops-nic/insigna-webservice-java-client

Página | 36

Ejemplo:

Figura 19 - Ejemplo de uso de comando wsdl2java

En la imagen anterior se puede apreciar que en la primera línea se accede a la ruta donde

se encuentra la herramienta “wsdl2java” y en la segunda ingresamos el comando requerido, donde “X” es la ruta en donde se encuentra el archivo “INSIGNAWS.wsdl” y “X:\insignaCode” es la ruta

donde se creará el código.

La estructura de salida se aprecia en la siguiente imagen:

Figura 20 - Ejemplo del output del comando wsdl2java

Después de ejecutar el comando, el siguiente paso es copiar la carpeta “mx” que se creó y agregarla a la carpeta “src” del proyecto en el que se desarrollará el cliente java.

b) Mediante código

Importando la clase org.apache.cxf.tools.wsdlto.WSDLToJava (Contenida en la librería

Apache CXF ) y ejecutando su método main:

WSDLToJava.main(new String[] { "-d", "rutaDelOutput", "rutaDelWsdl\INSIGNAWS.wsdl"});

Ejemplo:

Página | 37

Figura 21 - Ejemplo de uso del método "main" de la clase WSDLToJava

La estructura de salida se aprecia en la siguiente imagen:

Figura 22 - Ejemplo del output del método "main" de la clase WSDLToJava

4.1.3. Cliente ejemplo

En la imagen siguiente se muestra el código ejemplo de una clase que funciona como cliente

del Web Service de INSIGNA:

Página | 38

Figura 23 - Ejemplo de clase que consume los servicios del Web Service de INSIGNA

Página | 39

A continuación se describe brevemente las partes que componen el código anterior

1. Configuración del Factory necesario para obtener la instancia del Web Service:

Figura 24 - Ejemplo de configuración del factory

Es importante notar que la url del web Service de INSIGNA usa el protocolo HTTPS, ya que si tratamos de conectarnos mediante un protocolo HTTP el servicio no será accedido.

IMPORTANTE: Es muy común que los sitios de Beta tengan certificados firmados por el

dueño del ambiente (mientras que los sitios de Producción sí tengan certificados firmados por una

Autoridad Certificadora como Verisign, GlobalSign o Symantec). Es por ello que al apuntar al ambiente Beta se requiere añadir el certificado HTTPS del Web Service a la lista de “trusted

certificates” de Java (archivo %JAVA_HOME%/lib/security/cacerts).

La herramienta Keytool (de Java) cuenta con un comando para realizar este import (Ver:

http://docs.acl.com/ax/310/index.jsp?topic=%2Fcom.acl.ax.admin.help%2Fsystem_administration%2Ft_importing_certificates_into_the_java_cacerts_file.html).

keytool -import -alias <alias> -keystore <cacerts_file> -trustcacerts -file <certificate_filename>

Dado que el certificado HTTPS de Producción del Web Service de INSIGNA sí está firmado por

una autoridad certificadora, no es necesario realizar esto al apuntar a Producción.

2. Configuración de la autenticación del usuario:

Para configurar la autenticación del usuario es necesario implementar una clase “Callback” que

realizará la obtención del password del usuario necesario para autenticarse en el Web Service de INSIGNA. El código de la clase se presenta a continuación:

http://docs.acl.com/ax/310/index.jsp?topic=%2Fcom.acl.ax.admin.help%2Fsystem_administration%2Ft_importing_certificates_into_the_java_cacerts_file.html

http://docs.acl.com/ax/310/index.jsp?topic=%2Fcom.acl.ax.admin.help%2Fsystem_administration%2Ft_importing_certificates_into_the_java_cacerts_file.html

Página | 40

Figura 25 - Ejemplo de clase Callback

El siguiente paso es usar el Callback en la configuración de la autenticación:

Figura 26 - Ejemplo de configuración de la autenticación del usuario

3. Configuración del cliente que consumirá el Web Service:

Página | 41

Figura 27 - Ejemplo de configuración del cliente

Es importante establecer tiempos suficientes o considerables para permitir a la aplicación

esperar por la conexión y el tiempo de respuesta de los servicios del Web Service, ya que si hay interferencias en la red podría ocasionar timeouts en la comunicación de los sistemas.

4. Llamada a métodos del Web Service:

En este punto ya se tiene todo listo para usar los servicios del Web Service de INSIGNA. A continuación se muestra una llamada al método getCfdiInfo:

Figura 28 - Ejemplo de llamada a métodos del Web Service

Al ejecutar el código anterior se obtendrá la siguiente salida:

Figura 29 -Ejemplo de salida de una ejecución de comando CfdiInfo

4.2. .NET


El propósito de esta sección es explicar el proceso de creación de clientes .NET, usando C#

y Visual Basic para consumir el Servicio Web de INSIGNA. Utilizaremos Microsoft Visual Studio

Página | 42

Community 2017 como plataforma de desarrollo, los pasos podrían variar ligeramente para versiones inferiores.

El código completo de este cliente se encuentra en la siguiente liga: https://github.com/cops-nic/insigna-webservice-.net-client.

4.2.2. Referencia del Web service

El primer paso para crear el cliente del servicio web es agregar la referencia del Web

Service de INSIGNA al proyecto en que estará nuestro cliente.

El proceso para agregar la referencia es el siguiente:

1) Seleccionar el proyecto al cual consumirá el servicio web :

Figura 30 - Ejemplo de agregación de referencia de un servicio web, selección del proyecto

2) Ingresar la URL del Servicio Web de INSIGNA y especificar el namespace que queremos usar para identificar las clases que se generarán.

https://github.com/cops-nic/insigna-webservice-.net-client

https://github.com/cops-nic/insigna-webservice-.net-client

Página | 43

Figura 31 - Ejemplo de creación de referencia de un servicio web, especificación de URL del servicio

Al realizar el paso anterior, tendremos importadas las clases del Servicio Web al proyecto.

4.2.3. Configuración de la conexión

El siguiente paso es configurar la aplicación para que se conecte al Servicio Web. A

continuación se muestra un ejemplo del archivo “app.config” configurado para realizar la conexión.

Página | 44

Figura 32 - Ejemplo de configuración de conexión en .NET

A continuación se describen brevemente las partes que componen el código anterior:

Configuración del Binding que indicará al cliente la forma en la que se transmiten los

mensajes al servidor.

Figura 33 - Ejemplo de configuración del binding

Página | 45

Configuración del endpoint:

Figura 34 - Ejemplo de configuración del endpoint

En este punto ya se tiene todo listo para usar los servicios del servicio web de INSIGNA, el siguiente paso es crear el cliente.

4.2.4. Cliente ejemplo en C#

A continuación se muestra el código de implementación de un cliente que consume el servicio web de INSIGNA en C#:

Página | 46

Figura 35 - Ejemplo de cliente en C#.

Página | 47

NOTA: Es necesario reemplazar el usuario y password con las credenciales del usuario de

pruebas público para que este cliente de ejemplo funcione correctamente.

4.2.5. Cliente ejemplo en Visual Basic

A continuación se muestra el código de implementación de un cliente que consume el servicio

web de INSIGNA en Visual Basic:

Figura 36 - Ejemplo de cliente en Visual Basic.

Página | 48



Al ejecutar cualquiera de los dos clientes anteriores obtendremos el siguiente resultado:

Figura 37 - Ejemplo de Output del cliente en .NET cuando se consulta un cfdi

4.3. DELPHI


El propósito de esta sección es explicar el proceso de creación de un cliente Delphi usando RAD

Studio 10.2 como entorno de desarrollo, el proceso puede cambiar en otras versiones.


nic/insigna-webservice-delphi-client.

4.3.2. Unidad InsignaWs

El primer paso para crear el cliente es agregar la definición del Servicio Web de INSIGNA al

proyecto en que estará nuestro cliente, es decir, crear la unidad InsignaWS.

El proceso para agregar la unidad es el siguiente:

1. Si se está usando la versión 10.2 este paso no es necesario (saltar al paso 2). En versiones previas no se permitía importar automáticamente el XSD de Insigna en el WSDL con la etiqueta

import, por lo que es necesario primero descargar el WSDL desde la url https://beta.ws.insigna.mx/services?wsdl.

La estructura del wsdl se muestra en la siguiente imagen:

https://github.com/cops-nic/insigna-webservice-delphi-client

https://github.com/cops-nic/insigna-webservice-delphi-client


Página | 49

Se necesita reemplazar la parte del WSDL que esta delimitada por el rectángulo azul con el contenido del XSD, el cual podemos descargar desde la url que viene en el atributo

schemaLocation y esta subrayada con rojo (https://beta.ws.insigna.mx/services?xsd=InsignaSOAPWSService_schema1.xsd). La estructura

del WSDL modificado se muestra en la siguiente imagen:

La parte delimitada por el rectángulo azul corresponde al XSD que se incrustó manualmente dentro del WSDL, por cuestiones de tamaño de la imagen solo se muestra una parte del

archivo, una vez hecho esto, se guarda el WSDL localmente y se procede a importarlo.

2. Dentro del RAD Studio, después de crear el proyecto para el cliente, seleccionar la opción del menú “Component>Import WSDL…” (la ubicación de esta opción puede variar dependiendo de

la versión usada):

Figura 38 - Ejemplo de la importación del WSDL, parte 1

3. Ingresar la URL del Servicio Web de INSIGNA y hacer clic en “Next” dejando las opciones default del Wizard.

https://beta.ws.insigna.mx/services?xsd=InsignaSOAPWSService_schema1.xsd

Página | 50

Figura 39 - Ejemplo de la importación del WSDL, parte 2

IMPORTANTE:

Si realizó el paso 1, en la url del WSDL se tendría que buscar el que se generó manualmente, en

otro caso basta con colocar la url del WSDL del Web Service de INSIGNA tal como se muestra en la

imagen.

Al realizar el paso anterior se creará la unidad “services” dentro del proyecto con la

definición de las clases del Servicio Web de INSIGNA:

Figura 40 - Ejemplo de la estructura del proyecto al terminar de crear la unidad services

Para fines prácticos, renombremos la unidad a “InsignaWS”.

Página | 51

Abrimos la unidad que acabamos de renombrar y nos dirigimos hacia las ultimas líneas de

esta. Ya que estemos ahí, veremos unas líneas como las siguientes:

En la imagen anterior, el tercer argumento del metodo RegisterXSClass tiene la primera letra en

mayúscula (marcada con rojo), dicha letra se tiene que cambiar a minúscula para que las peticiones

SOAP puedan funcionar de forma correcta.

4.3.3. Unidad WSSecurity

El siguiente paso es añadir al proyecto la unidad “WSSecurity” que contiene la estructura del

header de autenticación que se usará en las peticiones del cliente:

Figura 41 - Ejemplo de como agregar una unidad al proyecto

Sobrescribimos el contenido del archivo con el siguiente código:

Página | 52

Página | 53

Página | 54

Página | 55

Figura 42 - Código de la unidad WSSecurity

Página | 56

4.3.4. Unidad Client

Lo siguiente es agregar una unidad llamada “Client” y sobreescribir el contenido de la misma

con el código que se muestra a continuación. En esta unidad es donde se llaman los métodos del servicio web de INSIGNA:

Página | 57

Figura 43 - Ejemplo de una unidad Cliente que hace llamadas a los métodos del Servicio web de INSIGNA

A continuación se describen brevemente las partes que componen el código anterior:

1. Definición de la clase

Página | 58

Figura 44 - Ejemplo de la sección de definición de una clase



2. Implementación de los procedure y functions

Página | 59

Figura 45 - Ejemplo de la sección de implementación de una clase

Página | 60


El último paso es usar las unidades que se definieron anteriormente para consumir el Servicio

Web. A continuación se muestra un ejemplo de cómo realizarlo:

Página | 61

Figura 46 - Ejemplo de cliente en Delphi

Al final la estructura del proyecto se vería como se muestra en la siguiente imagen:

Al ejecutar el proyecto obtendremos el siguiente resultado:

Figura 47 - Ejemplo de Output del cliente en Delphi, cuando se quiere cancelar un CFDI que no existe

Ya que el uuid mandado a cancelar no se encuentra en el sistema de INSIGNA, el Web Service

responde con un código de error 4232 porque se interpreta como cancelación de un cfdi externo.

Recibir este código de respuesta significa que el cliente creado funciona correctamente.

Página | 62

4.4. Python


El propósito de este documento es describir el proceso de creación de un cliente usando el lenguaje Python para consumir el Servicio Web de INSIGNA. Para iniciar el desarrollo es necesario

contar con:

1. Python versión 2.6 (https://www.python.org/downloads/windows/).

2. IDE Eclipse 4.6 (NEON). 3. Pydev (http://www.pydev.org/manual_101_install.html), Plugin para el desarrollo de

proyectos Python en Eclipse. 4. Directorio suds (https://pypi.python.org/pypi/suds), librería de Python para el desarrollo de

clientes de Web Services.


nic/insigna-webservice-python-client.

4.4.1.1. Librería Suds

El primer paso para crear el cliente es hacer uso la librería “Suds”. Una vez descargarda dicha librería hay que descomprimirla para obtener el directorio “suds”:

Figura 48 - Ejemplo de librería “Suds” descomprimida

https://www.python.org/downloads/windows/

http://www.pydev.org/manual_101_install.html

https://pypi.python.org/pypi/suds

https://github.com/cops-nic/insigna-webservice-python-client

https://github.com/cops-nic/insigna-webservice-python-client

Página | 63

Lo siguiente es agregar este directorio “suds” y todo su contenido al proyecto donde estará el

cliente Python:

Figura 49 - Ejemplo de la estructura del proyecto al agregar el directorio “suds” de la librería Suds

Al realizar el paso anterior ya podremos usar las clases de la librería para crear el cliente

del Web Service de INSIGNA.

4.4.2. WsSecurity

El siguiente paso es crear la clase que realizará la autenticación del cliente al Servicio Web. A

continuación se muestra un ejemplo de cómo realizarlo:

Página | 64

Figura 50 - Código de la clase WsSecurityHeader


A continuación se muestra el código de implementación de un cliente que consume los métodos del Web Service de INSIGNA:

Página | 65

Figura 51 - Ejemplo de un Cliente que hace llamadas a los métodos del Web Service de INSIGNA

NOTA: Es necesario reemplazar el usuario y password con las credenciales del usuario de pruebas

público para que este cliente de ejemplo funcione correctamente.

Al ejecutar el cliente se obtendrá algo similar al siguiente resultado:

(CfdiInfoResult){ responseCode = 205 responseDescription = "UUID No existe" transactionId = "tr1" serverTransactionId = "4670" requestDate = 2018-01-01 11:23:25 responseDate = 2018-01-01 11:23:25.000877 executionTime = 877

}

Figura 52 - Ejemplo de Output del cliente en Python, cuando se quiere consultar un CFDI no se encuentra en el sistema de Insigna

4.5. PHP


El propósito de esta sección es explicar el proceso de creación de un cliente PHP para consumir el Web Service de INSIGNA. Se utilizará notepad++ como herramienta para el desarrollo,

el motor de PHP versión 7.2.0 y la línea de comandos de Windows.

Página | 66

Antes de comenzar con el desarrollo del cliente es necesario activar las extensiones soap y openssl dentro del archivo de configuración php.ini como se muestra en la siguiente imagen (los

nombres de estas extensiones pueden ser diferentes dependiendo de la versión de PHP usada):

Se recomienda que la ruta de instalación de PHP sea “C:\php” ya que PHP buscará por default

en la ruta “C:\php\ext” las extensiones antes mencionadas.


nic/insigna-webservice-php-client.

4.5.2. Cliente Ejemplo

4.5.2.1. Clase InsignaClient

A continuación se muestra el código de la clase InsignaClient que se conecta al Web Service

de INSIGNA:

https://github.com/cops-nic/insigna-webservice-php-client

https://github.com/cops-nic/insigna-webservice-php-client

Página | 67

Página | 68

Figura 53 - Ejemplo de clase base para la implementación de la funcionalidad básica del cliente soap.

Se deben crear subclases que hereden de esta clase para cada una de las funciones que ofrece el

Web Service.

Página | 69

4.5.2.2. Clase CfdiInfoWrapper

A continuación se muestra el código de la clase CfdiInfoWrapper, la cual hereda de InsignaClient e

implementa métodos y propiedades para llamar a la función cfdiInfo del Web Service.

Página | 70

Figura 54 - Ejemplo de una subclase que hereda de la clase base InsignaClient la cual es utilizada para obtener la información de un cfdi.

Página | 71

4.5.2.3. Consulta de cfdi utilizando la clase CfdiInfoWrapper

A continuación se muestra un script que hace uso de la clase CfdiInfoWrapper para hacer la

llamada a cfdiInfo del Web Service de INSIGNA:

Figura 55 - Ejemplo de script para ejecutar el cliente PHP.

NOTA: Es necesario reemplazar el usuario y password con las credenciales del usuario de pruebas público para que este cliente de ejemplo funcione correctamente.

En esta sección muestra la sintaxis para ejecutar un script PHP en línea de comandos:

Figura 56 - Ejemplo de como ejecutar un script php en la línea de comandos de Windows.

A continuación se muestra la respuesta que manda el Web Service de INSIGNA al ejecutar el script

creado previamente:

Figura 57 - Datos de salida devueltos por el script ejecutado.

Web Service - INSIGNA · 2018-11-02 · El Web Service de INSIGNA es un servicio basado en SOAP que...

Documents

Transcript of Web Service - INSIGNA · 2018-11-02 · El Web Service de INSIGNA es un servicio basado en SOAP que...