Skip to content

Infraestructura

Jump to bottom
Andres Ramos edited this page Nov 27, 2023 · 4 revisions

General

Esta solucion esta conformada de dos applicaciones: un Web API y un Worker Service.

El Web API es el servicio web a donde se mandan todas las solicitudes. Este servicio esta administrado por AR Software y debes obetner una licencia para poder usarlo. La direccion URL de este servicio es https://contpaqiapim.azure-api.net/comercial

El Worker Service o Sincronizador es un servicio que se instala localmente en el servidor de CONTPAQi y se encarga de procesar las solicitudes enviadas a la API en el sistema CONTPAQi Comercial Premium.

Flujos De Trabajo

Enviar Solicitud

  1. Envia tu solicitud a la API en [POST] /api/Requests
  2. La API valida to solicitud
  3. Si tu solicitud es valida la API agrega tu solicitud en la base de datos y notifica al Sincronizador que hay una nueva solicitud por procesar
  4. La API te retorna tu solicitud con un Status: 201 Created, Id y Status: "Pending"
  5. Si tu solicitud no es valida la API te retorna un Status: 400 BadRequest y el mensaje de error
  6. Guarda el Id ya que deberas consultar el estatus y respuesta de la solicitud por Id en [GET] /api/Requests/{id}

Procesar Solicitud

  1. El Sincronizador se conecta con la API y espera a ser notificado de que hay solicitudes nuevas por procesar
  2. El Sincronizador valida tu solicitud
  3. Si tu solicitud es valida el Sincronizador procesa tu solicitud en CONTPAQi Comercial Premium
  4. El Sincronizador envia la respuesta con el resultado de tu solicitud a la API
  5. La API asocia la respuesta a tu solicitud

Consultar Solicitud

  1. Deberas consultar el estatus y respuesta de la solicitud por Id en [GET] /api/Requests/{id}
  2. Si el status de la solicitud es Pending la solicitud no ah sido procesada y deberas consultar el estatus de la solicitud mas tarde.
  3. Si el status de la solicitud es Processed la solicitud ya fue procesada.
  4. Puedes consultar la respuesta de la solicitud en el campo response de la solicitud.

Web API

El Web API es el servicio web a donde enviaras todas tus solicitudes. Esta diseñada para trabajar principalmente con los dos siguientes modelos: ApiRequest y ApiResponse. Puedes encontrar mas informacion sobre estos modelos en el repositorio ARSoftware.Contpaqi.Api.Common.

Solicitudes

Headers

Cuando envias una solicitud HTTP a la API debes agrear los siguientes Headers:

  • Ocp-Apim-Subscription-Key - Tu licencia de suscripcion al servicio web
  • x-Empresa-Rfc - El RFC de la empresa en CONTPAQi Comercial donde se va a procesar la solicitud
  • x-Esperar-Respuesta - Valor que indica a la API a esperar hasta 25 segundos a que el sincronizador termine de procesar la solicitud.

Errores

Error por no agregar el header Ocp-Apim-Subscription-Key:
{
    "statusCode": 401,
    "message": "Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API."
}
Error por agregar un header Ocp-Apim-Subscription-Key invalido:
{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}
Error por no agregar el header x-Empresa-Rfc:
{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "traceId": "00-219bc54c927d1020089d4ca6848e588f-fbce54e6bda05e65-00",
    "errors": {
        "x-Empresa-Rfc": [
            "The EmpresaRfc field is required."
        ]
    }
}

API Request

ApiRequest es la estructura de solicitudes con la que la API trabaja. Todas las ApiRequest tienen la misma estructura y se diferencian por el tipo y modelo de ContpaqiRequest.

Para mas informacion sobre las propiedades base del modelo ApiRequest puedes consultar el repositorio ARSoftware.Contpaqi.Api.Common.

CONTPAQI Request

Todas las ContpaqiRequest tiene la misma estructura y se diferencian por las propiedades "$type", model, options.

Estructura JSON de una ContpaqiRequest 

{
    "$type": "",
    "model": {},
    "options": {}
}
  • "$type" - El tipo de solicitud. E.g. para crear una factura el tipo seria CrearFacturaRequest y para crear un producto el tipo seria CrearProductoRequest.
  • model - Modelo de la solicitud. Todas las solicitudes tiene un modelo, aun si el modelo es un objecto vacio. Por ejemplo, la solicitud CrearFacturaRequest tiene el modelo CrearFacturaRequestModel.
  • options - Opciones de la solicitud. Todas las solicitudes tienen opciones, aun si las opciones es un modelo vacio. Por ejemplo, la solicitud CrearFacturaRequest tiene las opciones CrearFacturaRequestOptions.

El campo "$type" lleva el simbolo $ y debe ser siempre el primer campo del JSON

Convencion De Nombramiento

Como podras darte cuenta la convencion de nombramiento para:

  • Tipos de solicitud = [tipo de solicitud] + Request e.g., CrearFacturaRequest
  • Modelos de solicitud = [tipo de solicitud] + Request + Model e.g., CrearFacturaRequestModel
  • Opciones de solicitud = [tipo de solicitud] + Request + Options e.g., CrearFacturaRequestOptions

Ejemplos de API Request

Estructura JSON de una solicitud con un ContpaqiRequest de tipo BuscarEmpresasRequest:

{
    "id": "8ff41bb6-b5fb-4e82-7e3b-08db41a48abd",
    "subscriptionKey": "00000000000000000000000000000000",
    "empresaRfc": "URE180429TM6",
    "dateCreated": "2023-04-20T08:38:35.3890297-05:00",
    "contpaqiRequestType": "BuscarEmpresasRequest",
    "contpaqiRequest": {
        "$type": "BuscarEmpresasRequest",
        "model": {},
        "options": {
            "cargarDatosExtra": false
        }
    },
    "status": "Processed",
    "response": {}
}

Estructura JSON de una solicitud con un ContpaqiRequest de tipo CrearProductoRequest:

{
    "id": "f0a3610f-91e1-4177-c671-08db41b1b8ee",
    "subscriptionKey": "00000000000000000000000000000000",
    "empresaRfc": "URE180429TM6",
    "dateCreated": "2023-04-20T10:44:40.9005279-05:00",
    "contpaqiRequestType": "CrearProductoRequest",
    "contpaqiRequest": {
        "$type": "CrearProductoRequest",
        "model": {
            "producto": {
                "tipo": "Producto",
                "codigo": "PROD001",
                "nombre": "Producto 1",
                "claveSat": "43231500",
                "datosExtra": {
                    "CFECHAALTAPRODUCTO": "04/20/2023",
                    "CNOMBREPRODUCTO": "Producto 1",
                    "CCLAVESAT": "43231500",
                    "CTEXTOEXTRA1": "Texto Extra"
                }
            }
        },
        "options": {
            "cargarDatosExtra": false
        }
    },
    "status": "Pending",
    "response": null
}

Respuestas

API Response

ApiResponse es la estructura de respuestas con la que la API trabaja. Todas las ApiResponse tienen la misma estructura y se diferencian por el tipo y modelo de ContpaqiResponse.

Para mas informacion sobre las propiedades base del modelo ApiResponse puedes consultar el repositorio ARSoftware.Contpaqi.Api.Common.

CONTPAQI Response

El ContpaqiResponse almacena el resultado de la solicitud. Todas las ContpaqiResponse tienen la misma estructura y se diferencian por las propiedades "$type", model.

{
    "$type": "",
    "model": {}
}
  • "$type" - El tipo de respuesta. E.g. para crear una factura la respuesta seria CrearFacturaResponse y para crear un producto el tipo seria CrearProductoResponse.
  • model - Modelo de la respuesta y propiedad donde se almacena el resultado de la solicitud. Todas las respuestas tiene un modelo, aun si el modelo es un objecto vacio. Por ejemplo, la solicitud CrearFacturaResponse tiene el modelo CrearFacturaResponseModel.

Convencion De Nombramiento

Como podran darse cuenta la convencion de nombramiento para:

  • Respuestas de solicitud = [tipo de solicitud] + Response e.g., CrearFacturaResponse
  • Modelos de respuestas de solicitud = [tipo de solicitud] + Response + Model e.g., CrearFacturaResponseModel

Worker Service

El Worker Service o Sincronizador es un servicio que se instala localmente en el servidor de CONTPAQi y se encarga de procesar las solicitudes enviadas a la API en el sistema CONTPAQi Comercial Premium.

El sincronizador periodicamente escucha a ser notificado de que hay solicitudes pendientes por procesar y las procesa en Comercial. Una vez procesada la solicitud envia la respuesta a la API y repite el proceso.

Flujo de trabajo

  1. Inicializar el proceso
  2. Iniciar conexion con CONTPAQi Comercial
  3. Abrir empresa de trabajo
  4. Iniciar loop
  5. Buscar solicitudes pendientes por procesar
  6. Procesar solicitud
  7. Enviar la respuesta de la solicitud a la API
  8. Si es hora de apagarse terminar loop
  9. Ir a paso 5
  10. Cerrar conexion con CONTPAQi Comercial
  11. Terminar proceso
Clone this wiki locally