Passos da Integração

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:

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:

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:

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