Enlace B2B Manual del API

Transcripción

1 Enlace B2B Manual del API

2 LA INFORMACIÓN CONTENIDA EN ESTE DOCUMENTO PUEDE MODIFICARSE SIN PREVIO AVISO. Todas las declaraciones, información y recomendaciones en este documento se supone que son exactas pero son presentadas sin ninguna garantía de ningún tipo, explícita o implícita. Los usuarios deben tomar responsabilidad total de los productos. Para obtener la versión más actualizada de este documento contacte a su representante de soporte técnico. La reproducción total o parcial de este documento sin el permiso escrito de Tralix Corp. se encuentra estrictamente prohibida. Este documento puede incluir marcas y nombres comerciales para referirse a las entidades que son propietarias de los mismos o a sus productos. Tralix Corp. Renuncia a cualquier interés sobre la propiedad de marcas y nombres comerciales que no sean los suyos. Tralix Enlace B2B Manual del API Copyright 2011 Tralix Corporation

3 Versión: 1.0 Fecha de versión: 13/10/2014 Contenido INTRODUCCIÓN... 1 CLIENTE/SERVIDOR... 1 SIN ESTADO... 2 CACHÉ... 2 SERVICIOS UNIFORMES... 3 ARQUITECTURA EN CAPAS... 3 OBTENIENDO EL TOKEN (IDENTIFICADOR ÚNICO DE ENLACE EB2B)... 4 DOCUMENTACIÓN TÉCNICA... 6 PUERTO ASIGNADO PARA LOS SERVICIOS: CONSULTA DE CFDI RECIBIDOS... 6

4 Versión: 1.0 Fecha de versión: 13/10/2014 Introducción El Consorcio World Wide Web (W3C) es una comunidad internacional donde las organizaciones Miembro desarrollan estándares Webs, y han definido los Web Services como sistemas de software creados para soportar una interacción interoperable equipo a equipo sobre una red. Los Web Services suelen ser APIs Web que pueden ser accedidos dentro de una red (principalmente Internet) y son ejecutados en el sistema donde residen. El estilo de arquitectura que hemos utilizado es el REST (Representacional State Transfer), de tal manera que los servicios web deben cumplir con los siguientes principios: Un protocolo cliente/servidor sin estado: cada mensaje HTTP contiene toda la información necesaria para comprender la petición. Por lo que ni el cliente ni el servidor necesitan recordar ningún estado de las comunicaciones entre mensajes. Sin embargo, en la práctica, muchas aplicaciones basadas en HTTP utilizan cookies y otros mecanismos para mantener el estado de la sesión (algunas de estas prácticas, como la reescritura de URLs, no son permitidas por REST). Un conjunto de operaciones bien definidas que se aplican a todos los recursos de información: HTTP en sí define un conjunto pequeño de operaciones, las más importantes son POST, GET, PUT y DELETE. Con frecuencia estas operaciones se equiparan a las operaciones CRUD en bases de datos (ABMC: Alta, Baja, Modificación y Consulta) que se requieren para la persistencia de datos, aunque POST no encaja exactamente en este esquema. Una sintaxis universal para identificar los recursos. En un sistema REST, cada recurso es direccionable únicamente a través de su URI. El uso de hipermedios, tanto para la información de la aplicación como para las transiciones de estado de la aplicación: la representación de este estado en un sistema REST son típicamente HTML o XML. Como resultado de esto, es posible navegar de un recurso REST a muchos otros, simplemente siguiendo enlaces sin requerir el uso de registros u otra infraestructura adicional A continuación se ilustran estos fundamentos. Cliente/ Como servicios web, son cliente servidor y definen una interfaz de comunicación entre ellos, separando completamente las responsabilidades entre ambas partes. Cliente Continúa en la siguiente página 1

5 Introducción, continúa Sin estado Son servicios web que no mantienen estado asociado al cliente. Cada petición que se realiza a ellos es completamente independiente de la siguiente. Todas las llamadas al mismo servicio serán idénticas. Cliente A Cliente B Servicios Cliente C Sin estado Idénticos Cliente 1 Cliente 2 Caché El contenido de los servicios web REST se puede cachear de tal forma que una vez realizada la primera petición al servicio, el resto puedan apoyarse en el caché si fuera necesario. Cliente 1 2 Servicio Caché Continúa en la siguiente página 2

6 Introducción, continúa Servicios Uniformes Todos los servicios REST compartirán una forma de invocación y métodos uniforme utilizando los métodos GET, POST, PUT y DELETE. Cliente Arquitectura en capas Servicios distintos pero uniformes en invocación Todos los servicios REST están orientados hacia la escalabilidad y un cliente REST no será capaz de distinguir entre si está realizando una petición directamente al servidor, o se lo está devolviendo un sistema de cachés intermedio; o por ejemplo, existe un balanceador que se encarga de redirigirlo a otro servidor. Cliente Balanceador Servicios distintos pero uniformes en invocación Servicios distintos pero uniformes en invocación A continuación se indican los bloques de información que se consideran dentro de nuestra API. 3

7 Obteniendo el Token (identificador único de enlace EB2B) Para poder hacer uso de este web service, por seguridad, es necesario utilizar el identificador único del enlace B2B o también es conocido como Token. A continuación se describen los pasos a seguir para obtener este dato: 1.Ingresar al portal como usuario administrador. 2.Dar click en el nombre de usuario ubicado en la parte superior derecha, justo a un lado del botón "salir", se desplegara un menú. 3.Dar click en la opción "Configurar B2B", se desplegara una ventana. 4

8 4.Ubicar el texto: "Identificador único de su Enlace B2B", el código en negritas que se muestran al final de la línea es el token que estará utilizando para las llamadas al web service. 5

9 Documentación Técnica Puerto asignado para los servicios: 9050 Consulta de CFDI recibidos URL Parámetros requeridos Parámetros/filtros opcionales /TOKEN_ENLACE/RFC_RECEPTOR/cfdisRecibidos? TOKEN_ENLACE RFC_ENLACE todo (todo) aliasdivision (del receptor) razonsocial (del emisor) fecha (formato yyyy-mm-dd ej ) fechainicial (formato yyyy-mm-dd ej ) fechafinal (formato yyyy-mm-dd ej ) status(invalid o VALID) monto (X sin signo, ni símbolo de moneda) montoinicial (X sin signo, ni símbolo de moneda) montofinal (X sin signo, ni símbolo de moneda) lastdocumentnumber pagesize rfcemisor Método http GET 6

10 Descripción de Campos Seriefolio: Serie y folio interno del CFDI emitido por nuestro proveedor en la estructura de F- 1, donde F es la serie y 1 es el folio. Uuid: Identificador único del CFDI recibido. Estatus fiscal: Estatus fiscal de acuerdo a los usados en EB2B Rfc emisor: RFC del emisor del CFDI recibido Fecha emisión: Fecha de emisión del CFDI recibido Fecha recepción EB2B: Fecha en que se recibió el CFDI en la solución EB2B Total: Monto total del CFDI recibido Razón social proveedor: Razón social del emisor del CFDI recibido. Moneda: Moneda en que fue emitido el CFDI recibido. Si usted cuenta con algún dato adicional en las columnas de información del listado de CFDI recibidos en EB2B, usted podrá obtener esta información en la respuesta de su petición al web service, se incluirá al final de la respuesta base. Notas La respuesta del servicio se encuentra en texto plano, separado por pipes El parámetro todo devolverá la información de todos los CFDI recibidos, en caso de que se combine con otro parámetro, como por ejemplo fecha, se le dará prioridad sobre el todo El formato de las fechas para los filtros no se deben incluir datos de la hora El paginado (pagesize) por defecto es 20 y como máximo 100 En el header de la respuesta a la petición se encuentra el parámetro de lastdocumentnumber, con el cual podrán conocer el último documento para realizar desde ahí la siguiente consulta con los siguientes documentos. Ejemplo de Header: Content- Length:3644 Content- Type:text/plain; charset=utf- 8 nextpage:?lastdocumentnumber=c c3a736354d923e19a13ea2 Ejemplo de uso: abte578djdsdfge8eweqfhui986cdjkhs/ BMI U6/cfdisRecibidos?todo=todo& lastdocumentnumber=c c3a736354d923e19a13ea2 7

11 Códigos respuesta/errores 200 Request Petición exitosa 400 Bad Request Ocurre cuando no se incluyen los parámetros necesarios para obtener una respuesta ej. abte578djdsdfge8eweqfhui986cdjkhs/bmi u6/cfdisrecibidos? Como se ve aquí, no se incluye ningún parámetro por ello se da este error 404 Not Found - No existe Empresa con el RFC dado 404 Not Found - No existe Empresa con el Alias de sucursal dado 204 No Content No hay CFDI para la búsqueda solicitada 500 Internal Server Error Cualquier otro error en el servicio Ejemplo disrecibidos?todo=todo AA- 58 6E614B8A- 91FE- 4D3C- 9FBB- A6D5BBDC1941 Válido DCI021025M :40: :29:53 $ DIGITAL COLORS IMPRESORES S.A. DE C.V. AA- 57 D62EB09B- 4F6C- 4E45-983F- 8F73F0CF0DA4 Válido DCI021025M :38: :29:53 $ DIGITAL COLORS IMPRESORES S.A. DE C.V. AA- 59 BF99C3DA- B AFD1- B04F5428AE45 Válido DCI021025M :42: :29:58 $ DIGITAL COLORS IMPRESORES S.A. DE C.V. 8