get_licitacao

Instructions

Implementation Reference

• src/schemas/pncp.ts:31-62 (schema)

  ContratacaoSchema: Zod schema defining the response shape for a licitação (procurement bid). Includes fields like numeroControlePNCP, anoCompra, sequencialCompra, orgaoEntidade, modalidadeNome, objetoCompra, valorTotalEstimado, valorTotalHomologado, dates, etc.

  export const ContratacaoSchema = z
    .object({
      numeroControlePNCP: z.string(),
      anoCompra: z.number(),
      sequencialCompra: z.number(),
      numeroCompra: z.string().nullable().optional(),
      processo: z.string().nullable().optional(),
      orgaoEntidade: orgaoEntidadeSchema.nullable().optional(),
      unidadeOrgao: unidadeOrgaoSchema.nullable().optional(),
      modalidadeId: z.number().nullable().optional(),
      modalidadeNome: z.string().nullable().optional(),
      modoDisputaId: z.number().nullable().optional(),
      modoDisputaNome: z.string().nullable().optional(),
      srp: z.boolean().nullable().optional(),
      objetoCompra: z.string().nullable().optional(),
      informacaoComplementar: z.string().nullable().optional(),
      valorTotalEstimado: z.number().nullable().optional(),
      valorTotalHomologado: z.number().nullable().optional(),
      situacaoCompraId: z.number().nullable().optional(),
      situacaoCompraNome: z.string().nullable().optional(),
      dataPublicacaoPncp: z.string().nullable().optional(),
      dataAberturaProposta: z.string().nullable().optional(),
      dataEncerramentoProposta: z.string().nullable().optional(),
      dataInclusao: z.string().nullable().optional(),
      dataAtualizacao: z.string().nullable().optional(),
      linkSistemaOrigem: z.string().nullable().optional(),
      linkProcessoEletronico: z.string().nullable().optional(),
      amparoLegal: amparoLegalSchema.nullable().optional(),
      tipoInstrumentoConvocatorioCodigo: z.number().nullable().optional(),
      tipoInstrumentoConvocatorioNome: z.string().nullable().optional(),
    })
    .passthrough();

• src/adapters/pncp.ts:174-197 (helper)

  getContratacao: The downstream API call that fetches a single licitação from the PNCP consulta API endpoint. Includes caching (TTL_30_MIN) and error handling via PncpError.

  export async function getContratacao(
    orgaoCnpj: string,
    ano: number,
    sequencial: number,
  ): Promise<Contratacao> {
    const cacheKey = `get:contratacao:${orgaoCnpj}:${ano}:${sequencial}`;
    const cached = cache.get<Contratacao>(cacheKey);
    if (cached) return cached;
  
    try {
      // PNCP moved this detail endpoint from /api/pncp/v1 to /api/consulta/v1
      const { data } = await withRetry(() =>
        consultaClient.get(`/orgaos/${orgaoCnpj}/compras/${ano}/${sequencial}`),
      );
      const parsed = ContratacaoSchema.parse(data);
      cache.set(cacheKey, parsed, TTL_30_MIN);
      return parsed;
    } catch (err) {
      if (err instanceof AxiosError) {
        throw new PncpError(describeAxiosError(err), err);
      }
      throw err;
    }
  }