Sudrel API
Painel Criar chave de API

Documentação › Ajuda

Guias

Problemas comuns

O que fazer ao receber 401, 403, 404, 409, 412, 422, 429, webhook que não chega e nota parada.

Cada problema termina com o próximo passo. Se nenhum resolver, mande ao suporte o X-Request-Id da chamada.

Recebi 401

A chave não chegou ou não vale. Confira:

  • o cabeçalho é Authorization: Bearer sdr_..., com o espaço depois de Bearer;
  • a chave não foi revogada (painel, Integrações › Chaves de API);
  • o endereço tem o /api: https://api.sudrel.com.br/api/v1/....

Recebi 403

A chave não pode fazer isto. Duas causas:

  • Chave de teste (sdr_test_) em operação só de produção: criar ou alterar empresa, enviar certificado, ler documentos recebidos. Use uma sdr_live_.
  • Chave restrita a uma empresa acessando outra (acesso_negado) ou administrando webhooks (chave_restrita). Use uma chave sem restrição.

Recebi 404 numa nota ou empresa que existe

Ela existe no outro ambiente. A chave de teste só enxerga notas de teste, e a de produção só as de produção. Confira o prefixo da chave.

Recebi 412

A empresa não pode emitir: a prontidão tem um item em bloqueio. O corpo traz a lista em itens, com correcao em cada um. Corrija e emita de novo. Veja Prontidão.

Recebi 202

Não é erro. A nota está transmitindo e a Sudrel continua cuidando. Espere o webhook ou consulte GET /v1/nfse/{id}. Não emita de novo.

Recebi 409

Leia codigo:

  • referencia_duplicada: a nota já existe. Consulte pelo nfse_id do erro.
  • idempotencia_conflito: a mesma Idempotency-Key foi usada para outro corpo. Gere uma chave por nota.
  • conflito: a mesma Idempotency-Key ainda está em andamento. Espere alguns segundos e repita.
  • referencia_ambigua: a referência existe em duas empresas. Repita com ?empresa_id=.

Veja Idempotência.

Recebi 422

Leia codigo, e depois erros (cada um com campo, mensagem e correcao):

  • validacao: o JSON tem erro e nada foi criado. Corrija os itens de erros.
  • nfse_rejeitada: o Sistema Nacional recusou. Leia codigo_oficial e nfse.rejeicao.explicacao, corrija e emita uma nota nova.
  • tipo_invalido em /valor ou numa alíquota: mande como texto, "1500.00".

Recebi 429

Mais de 120 requisições no minuto nesta chave. Espere a virada do minuto e repita. Se acontece sempre, troque consultas repetidas por webhook e notas avulsas por lote.

O webhook não chegou

  1. Confira se o webhook assina o tipo de evento (GET /v1/webhooks/{id}) e se está ativo.
  2. Confira o ambiente: webhook criado com a chave de teste só recebe eventos de teste.
  3. Veja as tentativas em GET /v1/webhooks/{id}/entregas: status HTTP que o seu servidor devolveu, ou null quando nem conectou.
  4. Seu servidor precisa responder 2xx em até 10 segundos. Redirecionamento (3xx) não é seguido e conta como falha. Endereço de rede interna é recusado.
  5. Mande um teste: POST /v1/webhooks/{id}/teste.
  6. Recupere o que perdeu: POST /v1/webhooks/{id}/reenvio, ou leia GET /v1/eventos.

A assinatura do webhook não bate

  • Calcule o HMAC sobre o corpo bruto, os bytes exatos, antes de qualquer JSON.parse. Reserializar o JSON muda os bytes.
  • A chave do HMAC é o segredo como texto, do jeito que veio na criação.
  • Use o X-Sudrel-Signature-V2: o HMAC é de "<t>.<corpo>", não só do corpo.
  • Na troca de segredo vêm dois v1=: basta um bater.
  • Confira o relógio do servidor: a tolerância recomendada é de 5 minutos.

A nota parece travada

  1. GET /v1/nfse/{id}: veja status e a linha do tempo em eventos.
  2. transmitindo com aviso.codigo = "processamento_prolongado": a Sudrel ainda está cuidando. Não emita de novo.
  3. aguardando_confirmacao: está esperando você em POST /v1/nfse/{id}/confirmacao.
  4. falha_transmissao: leia falha.dps_enviada antes de qualquer coisa.
  5. Veja a situação do serviço na página de status.

Não encontro uma chamada que fiz

Procure pelo X-Request-Id (ou requisicao_id) em Integrações › Log da API, no painel. Ficam lá o pedido e a resposta, por 30 dias.