Passos da Integração

Owned by Diego Santos Nery
Last updated: Sept 09, 2024
2 min read

 

1. Passos para Configuração e Autenticação

A integração com a API da Serpro geralmente segue os passos abaixo:

1.1. Contratação do Serviço

  • Pré-requisito: Certificado digital e-CNPJ.

  • A contratação do serviço da API ocorre por meio do portal Serpro, onde você acessa a área do cliente e realiza a contratação do serviço de consulta NF-e.

1.2. Obtenção de Credenciais

  • Após contratar o serviço, você obterá uma Consumer Key e um Consumer Secret que serão usados para autenticação.

  • Esses dados estão disponíveis na área do cliente no portal do Serpro.

1.3. Autenticação OAuth2

  • A API utiliza o protocolo OAuth2 para autenticação.

  • Para gerar o token de acesso, envie uma requisição ao endpoint de autenticação com as credenciais obtidas.

Exemplo de Requisição de Autenticação:

bash

Copiar código

POST https://apicenter.serpro.gov.br/auth/token Content-Type: application/x-www-form-urlencoded Authorization: Basic {Base64(ConsumerKey:ConsumerSecret)} grant_type=client_credentials

Exemplo de Resposta:

json

Copiar código

{ "access_token": "eyJhbGc...", "token_type": "Bearer", "expires_in": 3600 }

  • O token recebido deverá ser utilizado nas requisições subsequentes como parte do cabeçalho de autorização.

2. Exemplo de Requisição e Resposta

Consulta de Nota Fiscal (NF-e)

Requisição:

bash

Copiar código

GET https://apicenter.serpro.gov.br/v1/nfe/{chave} Authorization: Bearer {access_token}

Onde {chave} é a chave de acesso da nota fiscal eletrônica.

Exemplo de Resposta:

Copiar código

{ "status": "sucesso", "data": { "chave": "351908...", "emitente": { "cnpj": "12345678000195", "nome": "Empresa Exemplo" }, "destinatario": { "cpf": "98765432100", "nome": "João da Silva" }, "produto": [ { "descricao": "Produto A", "quantidade": 10, "valor": 100.00 } ], "valor_total": 1000.00, "data_emissao": "2024-09-01T10:30:00" } }

3. Dados Obtidos e Como Utilizá-los no Ciclo da NF

A API retorna diversos dados importantes sobre a NF-e, como:

  • Dados do Emitente: Nome e CNPJ da empresa emissora.

  • Dados do Destinatário: Nome e CPF ou CNPJ do destinatário.

  • Itens da Nota: Produtos, quantidades e valores.

  • Valor Total: Valor total da nota fiscal.

  • Data de Emissão: Quando a nota foi emitida.

Esses dados podem ser usados para:

  • Verificação da autenticidade da NF-e: Garantir que a nota é válida e foi emitida corretamente.

  • Atualização de sistemas internos: Inserir as informações da NF-e em sistemas de ERP ou contabilidade.

  • Monitoramento de transações: Usar os dados para verificar a conformidade de uma transação comercial.

4. Resolução de Problemas Comuns

4.1. Erro de Autenticação

  • Possível Causa: Token expirado ou credenciais inválidas.

  • Solução: Verifique as credenciais e gere um novo token de autenticação.

4.2. Chave de NF-e Inválida

  • Possível Causa: A chave de acesso da NF-e pode estar incorreta.

  • Solução: Verifique a chave e tente novamente. Confirme que a chave tem 44 dígitos.

4.3. Problemas de Conectividade

  • Possível Causa: Problemas de rede ou indisponibilidade da API.

  • Solução: Verifique sua conexão de rede e consulte a documentação da Serpro para ver se há alguma manutenção programada.

5. Procedimentos de Depuração

  • Sempre verifique os logs de requisições HTTP, incluindo o código de status retornado (como 200, 401, 404, etc.).

  • Utilize ferramentas como Postman ou cURL para testar e depurar as requisições manualmente.

  • Em caso de erro na resposta da API, confira o corpo da resposta JSON, que geralmente contém detalhes sobre o problema.

Com esses passos, a integração com a API de consulta de NF-e da Serpro deve ser bem-sucedida