Guia de Migração
para a Versão 2
Prazo: 30 de Junho de 2026
Após essa data, todos os endpoints da Versão 1 serão desativados. Realize a migração com antecedência para evitar interrupções.
Este prazo não será prorrogado.
Descontinuidade da Plataforma SOAP/XML (v1.00)
A Versão 1 da plataforma que utiliza a tecnologia SOAP/XML será descontinuada.
A Versão 2 da plataforma representa uma modernização completa da camada de integração. O suporte ao protocolo SOAP será encerrado, esta mudança de tecnologia se faz necessária tanto do ponto de vista de tecnologia quanto à adequação de novos formatos de dados como o CNPJ Alfanúmerico.
Este guia detalha o que precisa ser alterado em cada cenário: quem utilizava WebService (SOAP) e quem já utilizava REST/JSON na V1, mas ainda precisa atualizar endpoint e algumas estruturas de requisição.
O que muda na Versão 2?
Consulta descontinuada
A consulta PEFIN foi descontinuada pelo Serasa e não estará disponível na V2 da API.
Nova URL base (endpoint)
Independentemente do protocolo que você usava na V1, todas as chamadas devem ser redirecionadas para o novo endereço base. O domínio e a estrutura de path foram atualizados.
V1 — Encerrada em 30 de Junho de 2026
https://www.soawebservices.com.br/webservices/producao/... (Produção)https://www.soawebservices.com.br/webservices/test-drive/... (Homologação)
V2 — Novo endpoint
https://producao.soawebservices.com.br/api/v2/... (Produção)https://homologacao.soawebservices.com.br/api/v2/... (Homologacao)
Exclusivamente REST / JSON
O protocolo SOAP/WebService foi removido por completo. A V2 opera exclusivamente via REST + JSON. Quem já utilizava REST na V1 ainda precisa migrar, pois o endpoint é diferente e a estrutura de requisição foi aprimorada.
Novo formato de datas
Na V1 REST, datas eram aceitas em formato dd/MM/yyyy. Na V2, o padrão adotado é yyyy-MM-dd (ISO 8601), tanto nos parâmetros de entrada quanto nas respostas retornadas pela API.
V1 — Formato antigo
DataNascimento: "31/12/1990"
V2 — Formato ISO 8601
DataNascimento: "1990-12-31"
Novo formato de valores
Na V1 REST, valores eram aceitas em formato "100,00". Na V2, o padrão adotado é 100.00, tanto nos parâmetros de entrada quanto nas respostas retornadas pela API.
V1 — Formato antigo
Valor: "100,00"
V2
Valor: 100.00
Estou usando WebService (SOAP) — O que devo fazer?
Se a sua integração é via SOAP (referência WSDL, envelope XML, etc.), a migração envolve uma mudança de paradigma completa: você deixará de consumir um WebService e passará a fazer chamadas HTTP REST com corpo em JSON.
Remova a referência ao WSDL
Exclua do seu projeto qualquer referência de serviço SOAP gerada a partir do WSDL. Não há proxy gerado nem envelope XML na V2 — as chamadas são HTTP puro.
Implemente chamadas HTTP POST/GET com JSON
Utilize um cliente HTTP da sua linguagem (ex: HttpClient no .NET, fetch no JavaScript, requests no Python). O corpo da requisição deve ser JSON e o header Content-Type: application/json deve estar presente.
Atualize o endpoint para a URL base da V2
Todas as chamadas devem apontar para https://producao.soawebservices.com.br/api/v2/. Consulte a documentação para o path específico de cada produto.
Adapte o tratamento de resposta de XML para JSON
As respostas deixam de ser envelopes SOAP em XML e passam a ser objetos JSON. Substitua o parser XML pelo deserializador JSON nativo da sua linguagem.
Verifique os campos de data e revise o mapeamento
Os nomes de campos na resposta JSON da V2 podem diferir dos nomes dos elementos XML da V1. Revise o mapeamento de cada campo e ajuste as datas para o formato yyyy-MM-dd.
Já uso REST/JSON na V1 — O que precisa mudar?
Mesmo que você já esteja usando REST + JSON, a migração é obrigatória. O endpoint mudou, o formato de datas foi padronizado e alguns campos foram renomeados ou reorganizados.
Atualizar a URL base, em todos os seus endpoints configurados
Substitua:https://www.soawebservices.com.br/webservices/producao/
porhttps://producao.soawebservices.com.br/api/v2/.
Formato de datas:
Substitua:dd/MM/yyyy
poryyyy-MM-dd
Atualize todos os campos de data enviados nas requisições (ex: data de nascimento, data de emissão). As datas retornadas nas respostas também virão no novo formato ISO 8601.
Revise o mapeamento de campos na resposta
Alguns campos foram adicionados e/ou reorganizados na resposta JSON da V2 para maior consistência. Teste cada produto individualmente e ajuste o mapeamento no seu sistema conforme a documentação atualizada.
Novo CNPJ alfanumérico
Suporte exclusivo na Versão 2
A Receita Federal publicou um novo formato de CNPJ que incluirá caracteres alfanuméricos (letras e números). A Versão 1 não suporta e não suportará este novo formato. Sistemas que permanecerem na V1 não conseguirão consultar nem validar os novos CNPJs emitidos, podendo causar falhas críticas em operações fiscais e de integração de dados.
O campo CNPJ na V2 aceita string alfanumérica
Não envie o CNPJ apenas como número. Trate o campo como string no seu sistema para garantir compatibilidade com o novo formato que pode conter letras.
Remova validações numéricas de CNPJ
Se o seu sistema valida que o CNPJ é composto apenas por dígitos (ex: regex \d{14}), essa validação precisará ser revisada para aceitar o novo formato alfanumérico.
Revise seu banco de dados para suportar o formado novo
Certifique-se de que campos que armazenam CNPJ no seu banco de dados aceitam caracteres alfanuméricos (tipo VARCHAR em vez de NUMERIC) e que máscaras de entrada no front-end permitem letras.
Em 30 de Junho de 2026 a Receita Federal Brasileira irá mudar o formato para novos CNPJs, este formato novo ira suportar caracteres alfanuméricos, por exemplo:
Os CNPJ atuais NÃO serão modificados, somente os novos CNPJs que utilizarão o formato novo:
Formato antigo
CNPJ: "00.000.000/0000-00"
Formato Novo
CNPJ: "1Z.S4K.BLE/0001-42"
Caso necessite gerar um CNPJ no formato novo para testes, utilize o Gerador da Receita Federal:
https://servicos.receitafederal.gov.br/servico/cnpj-alfa/simular
Versão 1 × Versão 2 — Comparativo
https://www.soawebservices.com.br/webservices/producao/
https://producao.soawebservices.com.br/api/v2/
dd/MM/yyyy
yyyy-MM-dd
Documentos para testes
Ambiente de Homologação
Você pode usar os documentos abaixo para uso no ambiente de homologação
https://homologacao.soawebservices.com.br
Pessoa Física
CPF: "999.999.999-99"
Pessoa Júridica
Numérico:CNPJ: "99.999.999/9999-62"Alfanumérico:CNPJ: "VN.NWT.6EL/0001-03"CNPJ: "VN.NWT.6EL/4SDD-59"
Resumo: como realizar a migração
Acesse a documentação técnica da Versão 2
Consulte os endpoints, parâmetros, exemplos de requisição e resposta para cada produto que você utiliza.
Atualize a URL e o protocolo nas suas integrações
Substitua o endpoint e, se necessário, migre de SOAP para REST/JSON conforme descrito nas seções acima.
Ajuste campos de Datas, Valores e CNPJ
Padronize datas para ISO 8601 (yyyy-MM-dd) e garanta que o campo CNPJ seja tratado como string alfanumérica.
Teste em ambiente de homologação
Valide todos os fluxos em homologação antes de subir para produção. Em caso de dúvidas, acione nosso suporte técnico.
Precisa de ajuda com a migração?
Nossa equipe técnica está disponível para auxiliar em cada etapa. Abra um chamado ou consulte a documentação completa da Versão 2.
Ficou com dúvidas?
Tire suas dúvidas e descubra como podemos ajudar o seu negócio com a solução ideal. Nosso time está pronto para atender você!
Fale com um especialista
