O que é o SSA3 e como lidar com ele na prática
O SSA3 é um padrão XML exigido pelo governo federal para a transmissão de dados de contratações públicas pelos municípios e entidades da administração indireta. A especificação técnica foi elaborada pela Secretaria do Tesouro Nacional em parceria com o TCU e define exatamente quais campos precisam constar nos contratos, dispensas, inscrições e instrumentos similaris. Desde 2024 a obrigatoriedade foi reforçada e muitos entes ainda enfrentam problemas de validação na hora de enviar os loteamentos para o SisContratas.
ssa3 2025 data: o que mudou e por que a maioria dos municipios trava aqui
A versão 2025 trouxe algumas atualizações na estrutura do esquema XSD e na exigência de campos relativos ao Cadastro Nacional de Contratações Públicas (CNCP). O mais relevante para quem está implementando agora é que o campo tpInstituicao passou a ser validado de forma mais rigorosa e que a obrigatoriedade do identificador único da despesa se estendeu também às contratações de menor vulto. Se você estava dependendo de pular essa validação nos lotes menores, essa possibilidade simplesmente acabou. O que eu vejo todo dia são dois problemas recorrentes. O primeiro é a geração dos IDs das rubricas orçamentárias: muitos geradores automáticos criam identificadores com zero à esquerda ou com caracteres especiais que o validador rejeita. O segundo é a data de publicação no DOU — se você informar uma data de publicação diferente da data efetiva do contrato, o lote é rejeitado sem nenhum detalhamento no erro.
Eu precisei corrigir isso no ano passado em um município de médio porte que tinha cerca de 800 contratos para transmitir. O que funcionou foi separar a geração do XML da validação. Eu monto o lote completo em um arquivo temporário, rodo uma validação local contra o XSD antes de enviar, e só aí faço o upload no sistema. Isso reduz drasticamente o tempo de retrabalho porque o SisContratas não devolve mensagens de erro muito claras. Aqui vai um detalhe que ninguém conta nos manuais: o campo valorContrato precisa ser transmitido como string numérica sem formatação de milhar, mas com vírgula para decimais conforme a especificação. Diversas ferramentas comerciais usam o formato americano (ponto decimal) e rejeitam o lote silenciosamente na validação local, só explodindo no envio final. Configure seu gerador para usar a cultura pt-BR explicitamente antes de serializar o valor.
Outro ponto que causa dor de cabeça é a estrutura de repetição dos itens de despesa dentro do detalhamentoContratacao. A especificação permite múltiplos registros de cota orçamentária por item, mas o validador do governo exige que o somatório das cotas não exceda o valor total do contrato e que cada cota referencie um código MOG válido. Eu já vi gente passar dias tentando entender por que um lote de 400 contratos era rejeitado, quando na verdade três contratos tinham a cota orçamentária duplicada com valores que batiam fora por arredondamento de centavos. A correção foi rodar um script que agrupa as cotas por item e recalcula o percentual de cada uma proporcionalmente antes de gerar o XML.
Como montar e transmitir um lote SSA3 2025
O processo segue basicamente quatro etapas. Primeiro você exporta os dados do sistema de contratações do seu ente — seja ele qual for — e mapeia cada campo para a estrutura definida no XSD. Segundo, você gera o XML com os elementos obrigatórios. Terceiro, você compacta os arquivos em um lote ZIP que deve seguir a estrutura de diretórios especificada pela TCU. Quarto, você faz o upload pelo portal SisContratas e acompanha o resultado da validação. O XSD mais recente pode ser baixado diretamente do site do TCU na seção de normas e manuais técnicos. A versão atual é a 4.1 do SSA3. Guarde esse arquivo porque toda vez que for atualizar o gerador, o primeiro passo é validar contra a última versão disponível.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Dentro do XML, os elementos obrigatórios principais são: identificacaoTransmissor, dadosContratacao, objetoContratacao, partes, detalhamentoContratacao e informacoesFinanceiras. Cada um tem subcampos que podem variar conforme o tipo de instrumento — compra, prestação de serviço, locação, concessão. Não tente reaproveitar o mesmo modelo XML para todos os casos sem fazer o mapeamento adequado dos campos condicionais. O lote ZIP precisa ter uma estrutura bem específica. O arquivo raiz é o loteXSD4.1.xml, que contém o metadado do lote, e os arquivos individuais de cada contrato seguem em subdiretórios organizados por tipo de instrumento. Se você errar a nomenclatura do arquivo ou a hierarquia de pastas, o portal rejeita o lote inteiro, mesmo que todos os XMLs individuais estejam corretos. Eu costumo usar um script Python simples para montar essa árvore de diretórios a partir de uma lista de contratos exportada, e só depois empacotar o ZIP. Leva uns 10 minutos para escrever o script e elimina um tipo de erro que custa horas para debugar depois.
Erros mais comuns e como contornar
Vou listar os erros que aparecem com mais frequência nas validações, junto com a solução que costuma funcionar na prática. Erro 2001 — Campo obrigatório não preenchido: geralmente é o numeroContrato ou o dataAssinatura. A causa raiz costuma ser um campo vazio na base de dados original. A solução é rodar uma consulta de integridade antes de gerar qualquer XML para identificar registros com campos nulos ou vazios nos campos mapeados como obrigatórios.
Erro 3002 — Valor incompatível com a estrutura do elemento: quase sempre ligado a formatação numérica ou data. Relembre: datas no formato AAAA-MM-DD, valores numéricos sem separador de milhar e com vírgula decimal. Validar esses campos com expressões regulares antes da serialização evita esse erro na maioria das vezes. Erro 4005 — Falha na validação contra o XSD: nesse caso o validador não consegue nem identificar o problema específico. O mais comum é um namespace errado no cabeçalho XML ou um encoding divergente do esperado. Confirme que o declaration XML está com encoding="UTF-8" e que o namespace aponta para a versão correta do schema.
Erro 5010 — Divergência entre dados transmitidos e cadastro do CNCP: esse aparece quando o ente já tem cadastro prévio no CNCP e os dados enviados não batem com o que está registrado. Nesses casos é necessário sincronizar o cadastro do ente antes de transmitir os contratos. Se o cadastro estiver desatualizado, o validador rejeita tudo indiscriminadamente. Uma coisa que aprendi na prática e que vale a pena anotar: o tempo de validação no SisContratas varia bastante dependendo do tamanho do lote. Lotes com menos de 50 contratos costumam ser validados em poucos minutos. Lotes acima de 500 registros podem levar de 30 minutos a 2 horas. Se você está numa situação de fechamento de prazo e precisa transmitir rapidamente, divida o lote em partes menores e valide cada uma separadamente. Isso também facilita a identificação de qual contrato específico está gerando o erro.
Alternativas e limitações
O SSA3 é a via oficial e não há alternativa para cumprimento da obrigação legal. Porém, existem limites práticos que você precisa conhecer. O sistema do SisContratas não suporta lotes com mais de 1.000 contratos por vez em condições normais. Acima disso, o envio fica instável e a rejeição pode ocorrer por timeout sem feedback claro. Além disso, a plataforma tem janelas de manutenção programadas que podem atrasar a validação por dias, especialmente no final do exercício financeiro quando o volume de transmissão aumenta exponencialmente. Se o seu ente tem uma base de contratos muito grande e recursos limitados para desenvolvimento, considere contratar uma solução de terceiros especializada em transmissão SSA3. O mercado tem algumas opções consolidadas que já fazem o mapeamento, a geração e a validação dos lotes automaticamente. O custo varia, mas em muitos casos o investimento se paga rapidamente comparado ao tempo que a equipe interna gasta corrigindo erros de validação. Se você opta por desenvolver internamente, reserve pelo menos duas semanas para ajustes finos nos primeiros loteamentos — a curva de aprendizado é mais íngreme do que a documentação sugere.
O que mais salva no dia a dia é manter um log detalhado de cada transmissão, com os erros retornados pelo sistema e as correções aplicadas. Isso vira um banco de conhecimento que acelera bastante as próximas rodadas de envio e evita que você repita os mesmos erros meses depois quando precisar transmitir dados de outro período.
