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.

Para utilizar o Webservice, é necessário possuir uma assinatura premium. Verifique aqui os planos disponíveis.

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.

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.

Defasagem de atualização

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

Esse parâmetro funciona da seguinte maneira : caso não seja informado, os dados serão retornados com a data de última atualização disponível para esse CNPJ (normalmente inferior a 90 dias). Caso você precise que os dados sejam retornados mais atualizados do que esse padrão, você poderá informar nesse parâmetro a quantidade máxima de dias aceitável de defasagem. Assim, se a quantidade de dias aceitável for menor do que a última atualização, será feita uma consulta em tempo real junto a Receita Federal para obter os dados atualizados.

Porém note que a consulta em tempo real pode levar mais tempo para retornar e é 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 omitir esse parâmetro, assim os dados virão com a data de última atualização desse CNPJ.

Agora, se seu negócio exigir, por exemplo, defasagem máxima de atualização de 30 dias, você poderá especificar isso usando o parâmetro, conforme no exemplo a seguir :

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

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.