Exportar pesquisa em Json
Os dados públicos da promoção comercial agora podem ser exportados no formato JSON (JavaScript Object Notation), um padrão moderno e amplamente utilizado para intercâmbio de dados. Ao contrário do formato CSV, que representa dados de forma tabular e limitada, o JSON oferece maior flexibilidade, estrutura hierárquica e melhor compatibilidade com aplicações web e APIs modernas.
Isso significa que os usuários podem consumir os dados de forma mais eficiente, com suporte nativo em diversas linguagens de programação, além de facilitar o mapeamento direto para objetos em sistemas automatizados. Essa mudança promove uma integração mais robusta, segura e escalável com sistemas próprios, otimizando o uso das informações disponíveis.
Endereço de acesso:
Exemplos de resquisição
Curl
bash $ curl https://api.scpc.estaleiro.serpro.gov.br/v1/promocao-comercial/export/json?anoPromocao=0000
Python
python import requests URL = 'https://api.scpc.estaleiro.serpro.gov.br/v1/promocao-comercial/export/json?anoPromocao=0000' response = requests.get(URL) print(response.json())
Parâmetros de entrada
| Campo | Tipo | Tamanho | Obrigatório? | Observação |
|---|---|---|---|---|
| anoPromocao | inteiro | 4 | Sim | |
| uf | texto | 2 | Unidade federativa do Brasil. Somente promoções nesta abrangência serão consultadas. | |
| cnpjMandatario | texto | 14 | informar o CNPJ apenas com números e letras, sem separadores. | |
| nomeMandatario | texto | 300 | Informar nome do mandatário, ou trecho dele, para ser pesquisado. Também busca no nome dos aderentes | |
| modalidade | texto | 50 | Informar o tipo de promoção, que pode ser Concurso, Assemelhado a Concurso, Sorteio, Assemelhado a Sorteio, Vale-Brinde e Assemelhado a Vale-Brinde. | |
| numeroCertificado | texto | 20 | Número do certificado da promoção. Cada promoção, ao ser autorizada, recebe um número do certificado que é a identidade da promoção. | |
| nomePromocao | texto | 200 | Nome da promoção, ou trecho dele, que deseja ser procurado |
Retorno
O endpoint retorna os dados no formato JSON, organizados de maneira hierárquica para refletir com clareza as entidades envolvidas em uma promoção comercial.
📘 Estrutura de dados da Promoção Comercial (JSON)
Promoção
| Campo | Tipo | Descrição |
|---|---|---|
| numeroPromocao | Texto | Número identificador da promoção (ex: "2025/00065"). |
| nome | Texto | Nome da promoção. |
| modalidade | Texto | Tipo/modalidade da promoção (ex: "Vale-Brinde"). |
| numeroCA | Texto | Número do Certificado de Autorização da promoção. |
| codigoAutenticidade | Texto | Código único para validação/autenticidade. |
| situacao | Texto | Situação atual da promoção (ex: "AUTORIZADA"). |
| dataInicio | Data | Data de início da promoção no formato ISO (YYYY-MM-DD). |
| dataFim | Data | Data de término da promoção. |
| quantidadePremios | Inteiro | Quantidade total de prêmios. |
| valorTotal | Decimal | Valor total estimado da premiação. |
| quantidadeSeries | Inteiro | Quantidade de séries envolvidas. |
| abrangencia | Texto | Lista de UF separadas por vírgula. |
| mandatario | Mandatário | Dados da empresa responsável pela promoção. |
| apuracoes | Lista de Apuração | Lista com as etapas de apuração da promoção. |
Mandatário
| Campo | Tipo | Descrição |
|---|---|---|
| cnpj | Texto | CNPJ da empresa. |
| nomeFantasia | Texto | Nome fantasia da empresa. |
| razaoSocial | Texto | Razão social (pode ser null). |
| endereco | Texto | Nome da rua/avenida. |
| numero | Texto | Número do imóvel. |
| complemento | Texto | Complemento do endereço. |
| bairro | Texto | Bairro. |
| cidade | Texto | Cidade. |
| uf | Texto | Unidade Federativa (UF). |
| cep | Texto | Código de Endereçamento Postal. |
Apurações
| Campo | Tipo | Descrição |
|---|---|---|
| idApuracao | Inteiro | Identificador da apuração. |
| localApuracao | Texto | Local físico ou nome simbólico da apuração. |
| inicioApuracao | Data | Data e hora de início da apuração (pode ser null). |
| fimApuracao | Data | Data e hora de término da apuração. |
| inicioParticipacao | Data | Início do período de participação. |
| fimParticipacao | Data | Fim do período de participação. |
| premios | Lista de Prêmios | Lista de prêmios vinculados a esta apuração. |
| endereco | Texto | Endereço da apuração, se aplicável. |
| numero | Texto | Número do imóvel. |
| complemento | Texto | Complemento do endereço. |
| bairro | Texto | Bairro. |
| cidade | Texto | Cidade. |
| uf | Texto | UF. |
| cep | Texto | CEP. |
Prêmios
| Campo | Tipo | Descrição |
|---|---|---|
| descricao | Texto | Descrição do prêmio. |
| quantidade | Inteiro | Quantidade de prêmios com esta descrição. |
| valor_unitario | Decimal | Valor unitário estimado. |
| valor_total | Decimal | Valor total (quantidade × valor_unitário). |
| ordem | Texto | Ordem de exibição ou distribuição. |
| data_entrega | Data | Data prevista ou efetiva da entrega do prêmio. |