AEC Tenders icon

AEC Tenders

Fetches public construction tenders from Brazil's PNCP

Actions4

Overview

This node fetches detailed information about a specific public construction tender from Brazil's National Public Procurement Portal (PNCP) by its unique identifiers. It is designed to retrieve a single tender using the procuring entity's CNPJ (a 14-digit Brazilian company identifier), the year of the tender, and its sequential number.

Common scenarios where this node is beneficial include:

  • Verifying details of a particular tender for compliance or auditing purposes.
  • Integrating tender data into business workflows that require precise tender identification.
  • Fetching official tender information for reporting or analysis in construction, engineering, or public procurement sectors.

Practical example:

  • A user wants to get all details about a tender issued by a specific government agency in 2025 with sequence number 1. They provide the agency's CNPJ, the year 2025, and the sequence number 1 to retrieve the tender's full data record.

Properties

Name Meaning
Procuring Entity CNPJ The 14-digit CNPJ (Brazilian company identifier) of the procuring entity without any formatting (e.g., 12345678000190). This identifies the organization issuing the tender.
Year The year when the tender was issued (e.g., 2025).
Sequence Number The sequential number of the tender within the given year and procuring entity (e.g., 1).

Output

The output is a JSON object representing detailed information about the specified tender. Key fields include:

  • pncpId: Unique PNCP control number of the tender.
  • procuringEntityName: Name of the procuring entity.
  • procuringEntityCNPJ: CNPJ of the procuring entity.
  • tenderObject: Description of the contract or purchase object.
  • tenderModality: Type or modality of the tender process.
  • tenderSituation: Current status or situation of the tender.
  • publicationDate: Date when the tender was published.
  • proposalOpeningDate: Date when proposals are opened.
  • estimatedTotalValue: Estimated total value of the tender in BRL.
  • municipalityCode, municipalityName: Location details of the tender.
  • stateCode, stateName: State information.
  • unitName, unitCode: Specific unit within the procuring entity.
  • legalProcedure, legalDescription, legalCode: Legal framework details.
  • process, numeroCompra, anoCompra, sequencialCompra: Tender identification numbers.
  • linkSistemaOrigem: Link to the original system if available.
  • informacaoComplementar: Additional information.
  • dataEncerramentoProposta: Proposal closing date.
  • modoDisputaNome, tipoInstrumentoConvocatorioNome, justificativaPresencial: Various procedural details.
  • linkProcessoEletronico: Link to electronic process if available.
  • usuarioNome: User name associated with the tender entry.
  • currency: Always "BRL".
  • valorTotalHomologado: Total homologated value.
  • srp: Boolean indicating if SRP (Registro de Preços) applies.
  • dataInclusao, dataAtualizacao, dataAtualizacaoGlobal: Timestamps related to data inclusion and updates.
  • _extractedAt: Timestamp when data was extracted.
  • _category: Categorization of the tender based on keywords (e.g., infrastructure, architecture).
  • _riskScore: Calculated risk score based on tender attributes.
  • _dataQuality: Percentage score assessing completeness of key data fields.
  • _urgencyLevel: Urgency level based on publication and proposal dates (critical, high, medium, low).
  • portalUrl: Direct URL to the tender page on the PNCP portal if available.

No binary data is output by this node.

Dependencies

  • Requires access to the PNCP API endpoint at https://pncp.gov.br/api/consulta.
  • Needs an internet connection to make HTTP GET requests.
  • No explicit API keys or authentication tokens are shown in the code; however, the API may require valid credentials configured in n8n.
  • The node uses standard HTTP headers including a custom User-Agent and a unique request ID per call.
  • Handles rate limiting and retries with exponential backoff internally.

Troubleshooting

Common Issues

  • Invalid CNPJ format: The CNPJ must be exactly 14 digits without any punctuation or spaces. Providing an incorrectly formatted CNPJ will cause an error.
  • Tender not found: If no tender matches the provided CNPJ, year, and sequence number, the node throws an error indicating the tender was not found.
  • API rate limits exceeded: The PNCP API enforces rate limits. If too many requests are made in a short time, the node will throw a rate limit error advising to wait before retrying.
  • Network connectivity problems: Connection refused, DNS resolution failures, or timeouts will result in errors suggesting to check internet connectivity or try again later.
  • Timeouts: Long-running requests may timeout; the node retries with exponential backoff but may eventually fail if the API remains unresponsive.

Error Messages and Resolutions

  • "Invalid CNPJ format. It must contain exactly 14 digits": Check and correct the CNPJ input.
  • "Tender not found with the provided parameters": Verify the CNPJ, year, and sequence number are correct.
  • "Rate limit exceeded. Try again in X seconds": Wait the specified time before making new requests.
  • "Não foi possível conectar à API PNCP": Check your internet connection and API availability.
  • "Timeout na consulta à API PNCP": Consider reducing query frequency or retry later.
  • Other API errors include descriptive messages with HTTP status codes and details to help diagnose issues.

Links and References

This summary covers the static analysis of the node's execute method and related logic for the "Tender" resource and "Get By ID" operation.

Discussion