APIs Disponíveis

Todos os sistemas dos ambientes de desenvolvimento e homologação, devem apontar para o ambiente de homologação do Login Cidadão gov.br, pois a partir deste ambiente é que temos uma versão atualizada e estável.

As APIs são maior detalhadas nesta seção e também é disponibilizada uma URL com swagger para testes:

Swagger homologação:
- https://meu.hml.rs.gov.br/api/doc
Swagger produção:
- https://logincidadao.rs.gov.br/api/doc

API para Dados Extras de Empresas

Essa API foi criada para disponibilizar os dados extras de empresas fornecidas pelo Gov.Br, que são informações adicionais disponibilizadas, por este, para consulta e que podem ser utilizados para diversas finalidades. Essa API tem a responsabilidade de fazer o intercâmbio entre o serviço e o Gov.Br para disponibilizar a estes, essas informações adicionais.

Situação Atual da API

Esta API está atualmente nessa situação:

Homologação: disponibilizada em 26/09/2022.
Produção........: disponibilizada em 13/10/2022, às 08:00.

Premissas da API

Para poder requisitar essa API , alguns pré-requisitos são necessários:

o usuário precisa estar logado no Gov.Br;
precisa ter o escopo "govbrempresa" autorizado;
e precisa informar o CNPJ desejado.

Pode ser colocado qualquer CNPJ válido, mas se não tiver relação com o usuário logado, retorna o erro abaixo:

{
        "Gov.Br.errors": {
            "status": 404,
            "code": "COMPANYIDPARTICIPANT_MUSTFOUNDARECORD",
            "title": "Responsável de empresa não encontrado no govbr."
        }
    }

Para não ter esse tipo de problema, sempre consulte o campo "govbrEmpresasVinculadas" que retorna junto com os dados do usuário logado. Neste campo, vem um JSON com todas as empresas relacionadas a ele. Exemplo:

[
    {
        "cnpj"            :    "23456789000199",
        "razaoSocial"    :    "Nome da Empresa",
        "dataCriacao"    :    "2021-07-30T15:14:43.806-0300"
    }
    {
        "cnpj"            :    "98765432000122",
        "razaoSocial"    :    "Nome da Empresa",
        "dataCriacao"    :    "2022-06-15T13:24:41.007-0300"
    }
]

Caso não tenha nenhuma empresa relacionada, este campo retorna vazio.

Procedimento de Chamada da API

A utilização é bem simples, precisa apenas que o usuário esteja logado, com o escopo "govbrempresa" autorizado e fazer a chamada à URI da API, enviando um JSON com o CNPJ desejado:

{URL do Login Cidadão}/api/v2/person/login/govbr/dadosempresa

Passar no cabeçalho a informação:

Authorization: Bearer {Access Token}
Content-Type: application/json
Accept: application/json

E no JSON deve ter essa estrutura:

{

"cnpj": "23456789000199",

"cpf": "99999999999"

}

Onde:

CNPJ: deve ser um CNPJ válido e preferencialmente que esteja na lista relacionada no campo "govbrEmpresasVinculadas".
CPF: este campo é opcional. Se for enviar, precisa ser o mesmo do usuário logado. Mantido apenas para se ter alguma garantia a mais de que os dados estão corretos.

Retorno da Chamada a API

A chamada da API resulta, se houver relação entre o usuário logado e a empresa (CNPJ) informada, o JSON abaixo:

{

"cpf": "99999999999",

"atuacao": "SOCIO",

"cadastrador": true,

"cpfCadastrador": "-",

"dataCriacao": "2021-07-30T15:14:43.807-0300",

"dataExpiracao": "2024-07-30T15:14:43.807-0300"

}

Onde:

cpf: número do CPF que pode atuar com a empresa;
atuacao: Papel do CPF na empresa na Receita Federal. O conteúdo será SOCIO, CONTADOR, REPRESENTANTE_LEGAL ou NAO_ATUANTE. O NAO_ATUANTE representa CPF possui certificado digital de pessoa jurídica, porém não possui um papel na empresa na base da Receita Federal. Se CPF for colaborador, atributo atuacao não aparecerá.
cadastrador: Identifica se o CPF pode realizar cadastro de colaboradores para CNPJ. O conteúdo false determina que o CPF é um colaborador da empresa. O conteúdo true determina que o CPF é representante da empresa com certificado digital de pessoal jurídica.
cpfCadastrador: CPF do responsável por realizar cadastro do Colaborador. Se CPF apresentar atributo cadastrador com conteúdo true, o atributo cpfCadastrador aparecerá com "-".
dataCriacao: Mostra a data e hora da vinculação do CPF ao CNPJ. A mascará será YYYY-MM-DD HH:MM:SS.
dataExpiracao: Mostra a data e hora que o CPF poderá atuar com CNPJ. A mascará será YYYY-MM-DD HH:MM:SS.

Principais erros que podem retornar

A execução da API está sujeita a alguns códigos de erro que podem vir do Gov.Br, que são identificadas com "Gov.Br.errors", e do próprio Login Cidadão Gov.br, que são identificados como "LC.falha":

    {
        "Gov.Br.errors": {
            "status": 400,
            "code": "COMPANYID_MUSTHAVECNPJFORMAT",
            "title": "Parâmetro de path :cnpj com formato ou dígitos verificadores de CNPJ inválidos. Formato esperado: '#############', valor recebido '105885950010921'."
        }
    }
    {
        "Gov.Br.errors": {
            "status": 401,
            "code": "ACCESSTOKEN_MUSTBENOTEXPIRED",
            "title": "Access Token JWT expirado."
        }
    }
    {
        "Gov.Br.errors": {
            "status": 401,
            "code": "ACCESSTOKEN_MUSTBENOTEMPTY",
            "title": "Token não encontrado no cabeçalho HTTP Authorization. Formato esperado: Authorization: Bearer [Token JWT de usuário emitido pelo govbr]."
        }
    }
    {
        "Gov.Br.errors": {
            "status": 403,
            "code": "FORBIDEN",
            "title": "Nothing information returned!"
        }
    }
    {
        "Gov.Br.errors": {
            "status": 404,
            "code": "COMPANYIDPARTICIPANT_MUSTFOUNDARECORD",
            "title": "Responsável de empresa não encontrado no govbr."
        }
    }
    {
        "Gov.Br.errors": {
            "status": 405,
            "code": "METHOD_NOT_ALLOWED",
            "title": "Nenhuma informação foi localizada para o CNPJ '{CNPJ Informado}' para o usuário logado ('{CPF informado}')!"
        }
    }
    {
        "LC.falha": {
            "status": 406,
            "code": "PARAMETER_IS_REQUIRED",
            "title": "O CNPJ deve ser informado!"
        }
    }
    {
        "LC.falha": {
            "status": 409,
            "code": "INVALID_PARAMETER",
            "title": "O CPF informado é diferente do CPF do usuário logado! Este campo é opcional, não precisa ser enviado."
        }
    }
    {
        "LC.falha" => [
            "status": 412,
            "code": "PRECONDITION_FAILED",
            "title": "Deve ser utilizado o escopo apropriado para esse tipo de requisição!"
        ]
    }

API para Solicitação de Informações Adicionais

Essa API é na verdade uma chamada para um formulário dinâmico para o preenchimento de informações para cada escopo autorizado no serviço, onde ao ser confirmado, altera os dados do usuário na base de dados do Login Cidadão Gov.br, podendo ser utilizado posteriormente.

Situação Atual da API

Esta API está atualmente nessa situação:

Homologação: disponibilizada em 07/11/2022.
Produção........: disponibilizada em 16/11/2022, às 14:00.

Premissas da API

Para poder requisitar essa API , alguns pré-requisitos são necessários:

o usuário precisa estar logado no Login Cidadão Gov.br;
precisa ter o escopo desejado autorizado;
e o Client ID do serviço.

Pode ser utilizado qualquer escopo autorizado, com exceção daqueles que são de responsabilidade do Gov.br, que são:

CPF: escopo cpf.
Nome: qualquer variação deste escopo (name, full_name, first_name, ...).
E-mail: escopo email.
Telefone: escopos mobile e phone_number.
Foto: escopos picture e image.

Ao tentar alterar algum destes campos, a tela de erro abaixo é exibida:

E alguns escopos não possuem um formulário dinâmico de edição e nestes casos, a tela abaixo é exibida:

Procedimento de Chamada da API

A utilização é bem simples, o serviço que precisa de alguma informação específica do usuário e que este ainda não preencheu, pode chamar esta API, solicitando que o mesmo informe os dados para continuar o atendimento.

A chamada precisa de 3 informações para que o formulário dinâmico seja apresentado para o usuário:

01) Identificação do Serviço: precisa do Client Id, pois precisará validar a URL de retorno da chamada, pois após confirmar os dados do formulário, o Login Cidadão Gov.br, redireciona para essa URL de Redirecionamento do serviço, que precisa estar cadastrado no cadastro do mesmo.
02) URL de Redirecionamento: precisa da redirect_url, que é a página do serviço que tratará dos dados inseridos pelo usuário. Caso o usuário não preencha (Pular etapa), esta página pode testar e solicitar novamente ou simplesmente ignorar e seguir adiante ou simplesmente negar o acesso, mas esse tratamento fica por conta do serviço.
03) Escopo Desejado: precisa do scope, onde podem ser informados mais de um por vez, sendo montado uma tela única, com todos os campos para preenchimento, podendo ainda ser chamado quantas vezes o sistema precisar. Só deve se tomar o cuidado para que o serviço não fique em LOOPING infinito.

Com as informações acima e com o usuário logado, é só fazer a chamada à URI da API, nestes dois formatos:

{URL do Login Cidadão}/client/{Client Id}/dynamic-form?id_card_state=RS&redirect_url={URL de Redirecionamento}&scope={Escopo Desejado}
{URL do Login Cidadão}/dynamic-form?client_id={Client Id}&scope={Escopo Desejado}&id_card_state=RS&redirect_url={URL de Redirecionamento}

Observação:

A parte em azul (id_card_state=RS) só é utilizado em conjunto com o escopo id_cards, onde ele é de uso obrigatório. Aos demais escopos não causa efeito nenhum.

A URL de redirecionamento é opcional, mas de grande importância, pois define o que fazer após a conclusão da edição dos campos solicitados.

Os escopos mais utilizados e que possuem uma tela de edição são:

id_cards: documento de identidade;
birthdate: para informação da data de nascimento;
addresses: para cadastramento de endereço;
city: para o cadastramento da naturalidade, referente a cidade. Inclui os campos estado e país;
state: para o cadastramento da naturalidade, referente a estado. Inclui o campo país;
country: para o cadastramento da naturalidade, referente ao país.

Detalhe:

Podem ser utilizados mais de um campo, sendo relacionado com o sinal de "+". Isso faz com que seja montada uma tela apenas com todos os campos, para preenchimento de uma única vez.

Exemplo:

...&escopo=birthdate+city

Retorno da Chamada a API

A chamada da API retorna um formulário dinâmico para preenchimento e ao ser confirmado ou se o usuário resolver pular o preenchimento, o Login Cidadão gov.br redireciona para a URL informada, onde a aplicação pode tratar os dados recentemente solicitados.

O Formulário Dinâmico disponibiliza uma forma de interação com as aplicações, onde ao ser chamado providência o formulário para alteração dos dados dentro do cadastro do Login Cidadão Gov.br, onde para ter estes dados atualizados, a aplicação pode chamar a API:

{URL do Login Cidadão gov.br}/api/v2/person

Que devolve todos os escopos solicitados pelo serviço no momento da conexão.

Com estas novas informações em mãos, a aplicação pode tomar a decisão de:

Continuar: estando com os dados solicitados, dar seguimento no atendimento ao usuário.
Solicitar novamente: caso os campos solicitados não tenham sido preenchidos, a aplicação pode solicitar novamente e quantas vezes quiser, mas tomando o cuidado de não deixar o usuário em um looping infinito.
Não permitir que siga adiante: para resolver o caso acima, a aplicação pode fazer com que solicite o mesmo dado, caso não tenha sido preenchido, umas 3 vezes por exemplo e, caso o usuário continue a não preencher o campo, dar uma informação de que o dado é importante e que sem ele o processo não pode seguir adiante, dando a opção de tentar preencher de novo ou encerrar o atendimento.