Webservice - API

Documentação do Webservice do Wooki.

Você pode utilizar o Webservice através da API (Interface de Programação de Aplicativos) do Wooki para automatizar suas buscas.

Essa automatização é muito útil para evitar o trabalho manual quando existe a necessidade de efetuar muitas buscas. Para utilizar o Webservice não é necessário possuir avançados conhecimentos técnicos, basta ter uma aplicação que execute um GET utilizando HTTPS. Nesse GET você deve informar qual busca deseja utilizar, os parâmetros dessa busca e suas credencias de login (usuário e senha). Verifique abaixo todas as buscas disponíveis com o Webservice do Wooki e os dados retornados em cada uma:

CNPJ

get
/api/v1/cnpj/busca
Busca no Wooki através da {palavra-chave} para informações da Receita Federal.
get
/api/v1/cnpj/receitafederal
Realiza uma busca pelo {numero} do CNPJ na Receita Federal.

Endereço

get
/api/v1/endereco/cep
Realiza uma busca de endereço informando o CEP como parâmetro.
get
/api/v1/endereco/ibgecodigo
Realiza uma busca de município junto ao IBGE informando o código do município.
get
/api/v1/endereco/ibgemunicipio
Realiza uma busca de município junto ao IBGE informando o nome do município.

Membro

get
/api/v1/membro/acesso
Solicita informações sobre os acessos restantes e validade dos acessos.

Utilização

Com o Webservice do Wooki é possível:

  • Buscar muitas informações de forma rápida e simples
  • Sanear seu banco de dados
  • Validar dados informados por terceiros dentro da sua aplicação em tempo real
  • Integrar os dados em sua aplicação (servidor, desktop ou mobile)
  • Evitar o trabalho manual de preenchimento em formulários de cadastro de CNPJs

O endereço do webservice do Wooki é o mesmo do site, ou seja, https://wooki.com.br. Observe que as requisições devem ser feitas utilizado o protocolo HTTPS para garantir a criptografia dos dados.

Dependendo da defasagem de atraso escolhida através do parâmetro dias, as buscas utilizando o Webservice do Wooki serão assíncronas, isto é, deverão ser realizadas em duas etapas. A primeira é a requisição dos dados atualizados cuja reposta irá informar a quantidade de segundos para ser realizada a segunda requisição. A segunda requisição é idêntica a primeira, porém ela deverá ser feita após o tempo informado, e irá retornar os dados solicitados.

Exemplo de uma busca ao Webservice:

https://wooki.com.br/api/v1/cnpj/receitafederal?numero=00000000000191&dias=10&usuario=teste@wooki.com.br&senha=teste

Para todas as requisições os parâmetros usuario e senha são obrigatórios. No campo usuário você deverá informar o email de seu usuário no Wooki e no campo senha a sua senha que utiliza para fazer login no site.

Todos os parâmetros obrigatórios estão marcados com um sinal vermelho:    .

Caso a requisição tenha sido bem sucedida e os dados ainda estão sendo atualizados, você receberá uma resposta em como abaixo:

{
    "espera": 60,
    "msg": "Sua busca está sendo realizada, faça exatamente a mesma requisição em 60 segundos.",
    "status": 1
}

Para obter os dados da você deverá fazer novamente a mesma requisição após o tempo sugerido de 60 segundos. Caso faça a requisição em menos de 60 segundos, é possível que os dados ainda não estejam atualizados, nesse caso a mesma mensagem de retorno acima será exibida. Caso os dados tenham sido atualizados, você receberá a resposta final com os dados da busca. Os seus acessos serão decrementados apenas quando os dados da busca são retornados pelo Webservice.

É possível, que na sua primeira requisição, os dados já sejam retornados pois estão atualizados de acordo com a defasagem de atraso informado.

Os dados, por padrão, serão retornados no formato JSON. Caso deseje que o retorno seja em XML, basta informar na requisição um parâmetro adicional xml=1 como no exemplo abaixo:

https://wooki.com.br/api/v1/cnpj/receitafederal?numero=00000000000191&dias=30&xml=1&usuario=email@cadastrado.com.br&senha=12345

A reposta virá em XML:

<?xml version="1.0" encoding="UTF-8" ?>
<root>
<data_situacao_cadastral>3/11/2005</data_situacao_cadastral>
<socios>
<item>Nome: ALDEMIR BENDINE. Qualificação: 16-Presidente.</item>
<item>Nome: ADILSON DO NASCIMENTO ANISIO. Qualificação: 10-Diretor.</item>
<item>Nome: ADMILSON MONTEIRO GARCIA. Qualificação: 10-Diretor.</item>
</socios>
<aprovado_por>Aprovado pela Instrução Normativa RFB nº 1.470, de 30 de maio de 2014.</aprovado_por>
<atividade_principal>Bancos múltiplos, com carteira comercial (6422100)</atividade_principal>
<key name="@numero">00000000000191</key>
<key name="@grupo">cnpj</key>
<numero_inscricao>00.000.000/0001-91</numero_inscricao>
<situacao_cadastral>Ativa</situacao_cadastral>
<data_abertura>1/8/1966</data_abertura>
<key name="@metodo">receitafederal</key>
<efr>UNIÃO</efr>
<email_rf></email_rf>
<sites>
<item>www.bb.com.br</item>
</sites>
<titulo_estabelecimento>Direcao Geral</titulo_estabelecimento>
<capital></capital>
<msg>Busca de CNPJ realizada com sucesso.</msg>
<telefones>
<item>0800-7290722</item>
</telefones>
<atividades_secundarias>Outras atividades de serviços financeiros não especificadas anteriormente (6499999)</atividades_secundarias>
<data_consulta>27/01/15 16:28:09</data_consulta>
<bairro>Asa Norte</bairro>
<logradouro>St Saun Setor De Autarquias Norte</logradouro>
<numero>Sn</numero>
<situacao_especial></situacao_especial>
<cep>70040912</cep>
<complemento>Quadra05 Bloco B - Torre I Sala 101 201 301 401 501 601 701 801 901 1001 1101 1201 1301 1401 1501 1601</complemento>
<motivo_situacao_cadastral></motivo_situacao_cadastral>
<municipio>Brasilia</municipio>
<nome_empresarial>Banco do Brasil Sa</nome_empresarial>
<status>0</status>
<natureza_juridica>Sociedade de Economia Mista (2038)</natureza_juridica>
<data_emissao>27/1/2015</data_emissao>
<data_situacao_especial>0/0/0</data_situacao_especial>
<telefone_rf>(61) 3310-7474</telefone_rf>
<uf>DF</uf>
</root>

Defasagem de atualização

É possível realizar buscas em tempo real nos sites fontes para garantir máxima atualização dos dados, ou optar por buscar um dado previamente atualizado. As duas opções oferecem vantagens e desvantagens.

A defasagem de atualização dos dados é controlado pelo parâmetro dias.

Ao optar por uma busca em tempo real, os dados retornados serão os mais atualizados possíveis. Contudo nessa modalidade é possível que seja necessário fazer duas requisições ao Webservice. A primeira requisição disparará a atualização e a segunda requisição, que deverá ser feita alguns segundos ou minutos depois, irá retornar os dados atualizados. As duas requisições deverão ser exatamente iguais e, apenas requisições que retornem os dados da busca, decrementarão seus acessos.

Para obter mais velocidade no retorno dos dados você pode especificar um atraso em dias maior, um atraso que você considera aceitável para suas necessidades. Por exemplo, para efetuar uma busca na Receita Federal pelo CNPJ 00000000000191 aceitando até 30 dias de atraso a URL ficaria em:

https://wooki.com.br/api/v1/cnpj/receitafederal?numero=00000000000191&dias=30&usuario=email@cadastrado.com.br&senha=12345

O valor padrão, para o parâmetro dias, é de 90 dias para o atraso máximo. Você deve informar 0 no parâmetro dias para realizar a consulta em tempo real junto ao site fonte.

Códigos de retorno: status

Toda requisição ao Webservice deve retornar uma resposta em Json ou XML cuja variável status indica o código de retorno referente a requisição. Abaixo estão os possíveis valores de status:

  • 0 (zero): requisição feita com sucesso.
  • 1: requisição feita com sucesso, porém dados estão sendo atualizados; aguarde o tempo indicado e refaça exatamente a mesma requisição.
  • 2: requisição feita com sucesso, porém dado requisitado não existe no site fonte.
  • 3: erro, método inválido.
  • 4: erro, parâmetro inválido; verifique os parâmetros informados.
  • 5: erro, autenticação falhou; informe corretamente o usuário e senha
  • 6: erro, você não possui um plano de acessos para realizar a requisição; adquira mais acessos.
  • 7: erro, você não possui acessos restantes para realizar a requisição; adquira mais acessos.
  • 8: erro, ocorreu um erro ao processar sua requisição; contate o suporte técnico.
  • 9: erro, é necessário realizar todas as requisições utilizando o protocolo HTTPS.