Primeira chamada

Gere uma chave em Credenciais e mande-a no cabeçalho Authorization. Toda resposta é JSON em UTF-8.

# o que a empresa 14365828000158 já ganhou
curl https://licitacao.yanpaiva.com/v1/documentos/14365828000158 \
     -H "Authorization: Bearer rdr_live_8f3a1c2d_SEU_SEGREDO"

O documento pode vir com pontuação — 14.365.828/0001-58 e 14365828000158 chegam no mesmo lugar.

Autenticação

Toda rota /v1/ exige uma chave ativa:

Authorization: Bearer rdr_live_8f3a1c2d_SEU_SEGREDO

Para testar rápido no navegador, dá para passar ?api_key=… na URL. Não use isso em produção: a query string aparece em log de proxy, histórico e referer, e é assim que chave vaza.

Como é cobrado

A unidade de cobrança não é a requisição HTTP, é o bloco de paginação: cada 4 páginas da mesma consulta custam uma requisição.

Duas garantias importantes:

• Repetir não cobra de novo. O mesmo bloco da mesma consulta só é cobrado uma vez a cada 15 minutos — um F5 ou voltar uma página não gera cobrança.
• Mudar o filtro é consulta nova. A identidade da consulta são os parâmetros sem a página. Trocar uf, papel ou por_pagina começa outra cobrança — a ordem dos parâmetros na URL não importa.

Cada resposta diz exatamente o que aconteceu, no corpo e no cabeçalho:

"cobranca": {
  "cobrada": true,             // esta chamada custou uma requisição
  "bloco": 1,
  "paginas_gratis_ate": 4,     // pagine até aqui sem pagar de novo
  "proxima_cobranca_na_pagina": 5
}

X-Requisicao-Cobrada: 1
X-Bloco-Paginacao: 1

Consultar o consumo em /v1/conta nunca é cobrado.

Paginação

Todas as listas usam os mesmos dois parâmetros e devolvem o mesmo envelope.

"paginacao": {
  "pagina": 1,
  "por_pagina": 100,
  "total_itens": 3184,
  "total_paginas": 32,
  "tem_proxima": true
}

Perfil do documento

Retrato consolidado nos dois papéis, numa chamada só. Serve para decidir o que buscar depois sem varrer as listas.

{
  "documento": "14365828000158",
  "nome": "COMERCIAL DISCON LTDA",
  "como_fornecedor": {
    "contratos": 412,
    "valor_total": 38472190.55,
    "primeira": "2021-03-11",
    "ultima": "2026-07-29",
    "itens_ganhos": 5130,
    "licitacoes_ganhas": 780,
    "valor_homologado": 21903448.10,
    "desagio_medio": 18.44,
    "ufs": 6
  },
  "como_orgao": { "licitacoes": 0, "contratos": 0, "valor_homologado": 0 }
}

Contratos

Contratos assinados em que o documento aparece — como fornecedor (vendeu) ou como órgão (comprou).

Parâmetros

curl "https://licitacao.yanpaiva.com/v1/documentos/14365828000158/contratos\
?papel=fornecedor&uf=SP&de=2026-01-01&por_pagina=100" \
     -H "Authorization: Bearer $RADAR_KEY"

{
  "dados": [{
    "id": "14365828000158-1-000123/2026",
    "id_licitacao": "45358249000101-1-000044/2026",
    "numero_contrato": "123/2026",
    "objeto": "Aquisição de material de expediente",
    "papel": "fornecedor",
    "fornecedor_ni": "14365828000158",
    "orgao_cnpj": "45358249000101",
    "valor_global": 184300.00,
    "data_assinatura": "2026-03-14",
    "data_vigencia_fim": "2027-03-13",
    "uf": "SP", "municipio": "Campinas",
    "link": "https://pncp.gov.br/..."
  }],
  "paginacao": { ... }, "cobranca": { ... }
}

Licitações

As contratações (editais) ligadas ao documento. Aceita os mesmos papel, uf, de e ate dos contratos — aqui a janela de datas é a de publicação.

{
  "dados": [{
    "id": "45358249000101-1-000044/2026",
    "objeto": "Registro de preços para material de expediente",
    "modalidade": "Pregão - Eletrônico",
    "srp": true,
    "valor_estimado": 500000.00,
    "valor_homologado": 412880.00,
    "data_publicacao": "2026-02-02",
    "data_encerramento_proposta": "2026-02-18T13:00:00+00:00",
    "aberta": false,
    "unidade_compradora": "Secretaria de Administração",
    "uf": "SP", "municipio": "Campinas",
    "link": "https://pncp.gov.br/..."
  }]
}

aberta é true enquanto a proposta ainda pode ser enviada — é o campo para filtrar oportunidade viva. Dispensa e inexigibilidade não têm prazo de proposta, então vêm com data_encerramento_proposta nula e aberta nula: isso é ausência de janela, não dado faltando.

Itens ganhos

Item a item, com preço unitário homologado e deságio. Só existe no papel de fornecedor — é o que a empresa vendeu, e por quanto. Aceita uf, de e ate (data de publicação).

{
  "dados": [{
    "id_licitacao": "45358249000101-1-000044/2026",
    "numero_item": 7,
    "item": "CANETA ESFEROGRAFICA AZUL",
    "catalogo_codigo": "278394",
    "unidade_medida": "UNIDADE",
    "quantidade": 12000,
    "estimado": 1.4800,
    "homologado": 0.9700,
    "total": 11640.00,
    "desagio": 34.4595,
    "orgao_nome": "Prefeitura Municipal de Campinas",
    "data_publicacao": "2026-02-02"
  }]
}

desagio é quanto abaixo do estimado o item saiu, em porcento. Vem null quando o valor estimado do órgão não é crível (há item real cadastrado a R$ 0,0001, que geraria deságio de milhões por cento) — null aqui significa "não dá para afirmar", não zero.

Consumo da chave

Quanto a chave já consumiu no mês. Não é cobrado.

{
  "chave": { "prefixo": "rdr_live_8f3a1c2d", "nome": "integração do ERP" },
  "mes_atual": { "requisicoes": 1840, "cobradas": 512, "limite": 5000 },
  "limites": { "por_minuto": 120, "por_pagina_max": 100 }
}

Erros

Todo erro vem no mesmo formato. Programe contra o codigo, que é estável; a mensagem é texto para pessoa ler e pode mudar sem aviso.

{ "erro": { "codigo": "limite_por_minuto",
            "mensagem": "Máximo de 120 requisições por minuto.",
            "limite_rpm": 120 } }

Um documento que existe mas não tem nada na base devolve 200 com dados: [] e total_itens: 0 — e não 404. "Não encontrei nada para este CNPJ" é uma resposta válida da busca, não uma rota inexistente.

Limites

• Por minuto: definido por chave, padrão 120. Ajustável em Credenciais.
• Por mês: opcional. Sem teto, a chave não trava — o consumo só é registrado.
• Itens por página: máximo 100.

O contador do minuto conta todas as chamadas, cobradas ou não: ele existe para proteger o servidor, e paginação dentro do bloco custa banco do mesmo jeito.