Problemas comunes

Cada problema termina con el siguiente paso. Si ninguno lo resuelve, envía a soporte el X-Request-Id de la llamada.

Recibí 401

La clave no llegó o no es válida. Revisa:

• el encabezado es Authorization: Bearer sdr_..., con el espacio después de Bearer;
• la clave no fue revocada (panel, Integrações › Chaves de API (Integraciones › Claves de API));
• la dirección tiene el /api: https://api.sudrel.com.br/api/v1/....

Recibí 403

La clave no puede hacer esto. Dos causas:

• Clave de prueba (sdr_test_) en una operación solo de producción: crear o modificar una empresa, enviar el certificado, leer documentos recibidos. Usa una sdr_live_.
• Clave restringida a una empresa accediendo a otra (acesso_negado) o administrando webhooks (chave_restrita). Usa una clave sin restricción.

Recibí 404 en una nota o empresa que existe

Existe en el otro entorno. La clave de prueba solo ve notas de prueba, y la de producción solo las de producción. Revisa el prefijo de la clave.

Recibí 412

La empresa no puede emitir: la preparación tiene un elemento en bloqueio. El cuerpo trae la lista en itens, con correcao en cada uno. Corrige y emite de nuevo. Ver Preparación.

Recibí 202

No es un error. La nota está en transmitindo y Sudrel sigue encargándose. Espera el webhook o consulta GET /v1/nfse/{id}. No emitas de nuevo.

Recibí 409

Lee codigo:

• referencia_duplicada: la nota ya existe. Consúltala por el nfse_id del error.
• idempotencia_conflito: la misma Idempotency-Key se usó para otro cuerpo. Genera una clave por nota.
• conflito: la misma Idempotency-Key todavía está en curso. Espera unos segundos y repite.
• referencia_ambigua: la referencia existe en dos empresas. Repite con ?empresa_id=.

Ver Idempotencia.

Recibí 422

Lee codigo, y después erros (cada uno con campo, mensagem y correcao):

• validacao: el JSON tiene un error y no se creó nada. Corrige los elementos de erros.
• nfse_rejeitada: el Sistema Nacional la rechazó. Lee codigo_oficial y nfse.rejeicao.explicacao, corrige y emite una nota nueva.
• tipo_invalido en /valor o en una alícuota: envíalo como texto, "1500.00".

Recibí 429

Más de 120 solicitudes por minuto en esta clave. Espera al cambio de minuto y repite. Si pasa siempre, cambia las consultas repetidas por webhook y las notas sueltas por lote.

El webhook no llegó

1. Verifica que el webhook esté suscrito al tipo de evento (GET /v1/webhooks/{id}) y que esté ativo.
2. Verifica el entorno: un webhook creado con la clave de prueba solo recibe eventos de prueba.
3. Mira los intentos en GET /v1/webhooks/{id}/entregas: el estado HTTP que devolvió tu servidor, o null cuando ni siquiera se conectó.
4. Tu servidor tiene que responder 2xx en hasta 10 segundos. La redirección (3xx) no se sigue y cuenta como falla. Una dirección de red interna se rechaza.
5. Envía una prueba: POST /v1/webhooks/{id}/teste.
6. Recupera lo que perdiste: POST /v1/webhooks/{id}/reenvio, o lee GET /v1/eventos.

La firma del webhook no coincide

• Calcula el HMAC sobre el cuerpo crudo, los bytes exactos, antes de cualquier JSON.parse. Volver a serializar el JSON cambia los bytes.
• La clave del HMAC es el secreto como texto, tal como vino en la creación.
• Usa el X-Sudrel-Signature-V2: el HMAC es de "<t>.<corpo>", no solo del cuerpo.
• Durante el cambio de secreto vienen dos v1=: basta con que uno coincida.
• Revisa el reloj del servidor: la tolerancia recomendada es de 5 minutos.

La nota parece trabada

1. GET /v1/nfse/{id}: mira status y la línea de tiempo en eventos.
2. transmitindo con aviso.codigo = "processamento_prolongado": Sudrel todavía se está encargando. No emitas de nuevo.
3. aguardando_confirmacao: te está esperando en POST /v1/nfse/{id}/confirmacao.
4. falha_transmissao: lee falha.dps_enviada antes que nada.
5. Mira la situación del servicio en la página de estado.

No encuentro una llamada que hice

Busca por el X-Request-Id (o requisicao_id) en Integrações › Log da API (Integraciones › Registro de la API), en el panel. Ahí quedan la solicitud y la respuesta, por 30 días.