¿Cómo extender la Web API?

La Web API de la versión 10 del ERP PRIMAVERA es una innovadora pieza de tecnología que permite a las empresas integrar el ERP con otros sistemas.

La Web API presenta, en forma de servicios REST, la mayoría de los métodos nativos de la API del ERP, pero hay otros que no se han tenido en cuenta. Al extender esta Web API es posible añadir nuevas funcionalidades que no están cubiertas de forma nativa, así como otras funcionalidades que el socio integrador necesite. Estos nuevos métodos utilizarán el mismo end point.

Procedimiento

Para demostrar la capacidad de extensión, en este artículo utilizaremos como ejemplo la impresión de un documento de ventas en formato PDF listo para su presentación.

Requisitos previos

• Primavera ERP con Web API instalada y con licencia
• Visual Studio & .NET Framework 4.7.1

Paso 1 - Crear el proyecto

En primer lugar, debe crear un proyecto con Visual Studio con el fin de crear una clase que añada más funcionalidades. Este proyecto debe ser del tipo Class Library (.NET Framework).

Paso 2 - Packages

Los siguientes packages deben añadirse al proyecto, prestando atención a sus versiones, ya que son las versiones utilizadas en las assemblies, tanto en el ERP como en la Web API:

• "Microsoft.AspNet.WebApi" version="5.2.6"
• "Microsoft.Owin" version="4.0.0"

Paso 3 - Nomenclatura de la clase

La clase añadida al proyecto debe cumplir dos requisitos para que la Web API la reconozca:

1. El primer requisito se refiere a su nombre. Debe tener, obligatoriamente, el sufijo Controller.
2. Esta clase también debe derivar de la clase Assembly System.Web.Http.ApiControler

public class ClassExtendedController: ApiController

En este ejemplo, llamamos a la clase "ClassExtendedController".

Paso 4 - RoutePrefix

Como cualquier clase de la Web API, esta también necesita la anotación RoutePrefix que debe ser igual al nombre de la clase, pero sin el sufijo Controller.

[/av_ePrefix("ClassExtended")]
public class ClassExtendedController: ApiController

Passo 5 - Codificação

Tal como explicado, o exemplo demonstrado será o de imprimir um documento de venda em formato PDF. Será um pedido HttpGet com a seguinte rota:

[Authorize]
[Route("PrintSalesDocToPDF/{TipoDoc}/{Serie}/{Numdoc}/{Filial}/{Numvias}/{NomeReport}/{SegundaVia}/{NomePDF}/{EntidadeFacturacao}")]
[HttpGet]

O código completo é o seguinte:

[Authorize]
[Route("PrintSalesDocToPDF/{TipoDoc}/{Serie}/{Numdoc}/{Filial}/{Numvias}/{NomeReport}/{SegundaVia}/{NomePDF}/{EntidadeFacturacao}")]
[HttpGet]
public HttpResponseMessage PrintSalesDocToPDF(string TipoDoc, string Serie, int Numdoc, string Filial, int Numvias, string NomeReport, bool SegundaVia, string NomePDF, int EntidadeFacturacao)
{
	try
	{
		HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.BadRequest);

		// Garantir que a extensão está definida
		if (string.IsNullOrWhiteSpace(Path.GetExtension(NomePDF)))
		{
			NomePDF += ".pdf";
		}

		// Garantir um local fisico para guardar o pdf gerado
		if (string.IsNullOrWhiteSpace(Path.GetDirectoryName(NomePDF)))
		{
			NomePDF = Path.Combine(Path.GetTempPath(), NomePDF);
		}

		// Imprime o documento para pdf via API
		bool imprimedocumento = ProductContext.MotorLE.Vendas.Documentos.ImprimeDocumento(TipoDoc, Serie, Numdoc, Filial, Numvias, NomeReport, SegundaVia, NomePDF, EntidadeFacturacao);

		// Prepara a resposta
		if (imprimedocumento)
		{
			var dataBytes = File.ReadAllBytes(NomePDF);
			var dataStream = new MemoryStream(dataBytes);

			byte[] buffer = new byte[0];
			buffer = dataStream.ToArray();

			var contentLength = buffer.Length;

			var statuscode = HttpStatusCode.OK;
			response = Request.CreateResponse(statuscode);
			response.Content = new StreamContent(new MemoryStream(buffer));
			response.Content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
			response.Content.Headers.ContentLength = contentLength;

			if (ContentDispositionHeaderValue.TryParse("inline; filename=" + NomePDF, out ContentDispositionHeaderValue contentDisposition))
			{
				response.Content.Headers.ContentDisposition = contentDisposition;
			}
		}

		return response;
	}
	catch (Exception ex)
	{
		throw new HttpResponseException(Request.CreateResponse(HttpStatusCode.BadRequest, ex.Message));
	}
}

Este serviço, que imprime um documento de venda, usa o método ImprimeDocumento que se encontra disponível na API do módulo de vendas. O acesso ao contexto do ERP está acessível na própria Web API, sem que seja necessário implementar qualquer outro mecanismo. Todas as questões de segurança estão também, desde já, garantidas.

O acesso ao contexto do ERP é dado pela classe ProductContext que se encontra na assembly Primavera.WebAPI.Integration, sendo necessário referenciar a mesma no projeto.

Passo 6 - Compilação e Deployment

Tendo tudo montado como explicado anteriormente, basta apenas compilar o projeto.

No output do projeto será gerada a assembly que terá de ser copiada para a pasta da Web API, tipicamente para a pasta "PRIMAVERA/SG100/Apl/WebApi/bin".

Passo 7 - Teste

Para testar este código pode ser usado o Postman.

Depois de pedido o token, pode ser feito o pedido para a impressão de um documento através da seguinte rota:

{{apiUrl}}ClassExtended/PrintSalesDocToPDF/{TipoDoc}/{Serie}/{Numdoc}/{Filial}/{Numvias}/{NomeReport}/{SegundaVia}/{NomePDF}/{EntidadeFacturacao}

O seguinte exemplo imprime uma via do documento GT C/1, da filial 000, usando o report GCPVLS01. A entidade a imprimir será a que corresponde à entidade de faturação e o nome do ficheiro a devolver terá o nome docGT1.pdf.

{{apiUrl}}ClassExtended/PrintSalesDocToPDF/GT/C/1/000/1/GCPVLS01/false/docGTC1/1

Como o Postman não tem um preview de documentos em formato PDF, na resposta podemos gravar o mesmo para um documento e validar se tudo aconteceu como esperado.

Conclusión

Crear extensiones para la Web API es la mejor manera de aprovechar todo el potencial que ofrece esta tecnología, sin tener que crear nuevos servicios web. De este modo, pueden implementarse todos los servicios no proporcionados de forma nativa, así como cualquier otro servicio resultante de un proceso de implementación.