API REST Timbrado

Documentación para integradores

Guía de integración para timbrado síncrono de CFDI 4.0 en producción.

Versión v1 · Detecno ClientGate · Junio 2026

Enlaces rápidos

Swagger UI…/timbrado-api/swagger

OpenAPI JSON…/timbrado-api/swagger/v1/swagger.json

Base URLhttps://<host>/timbrado-api

Esta guíahttps://<host>/timbrado-api/docs

HealthGET /timbrado-api/health

Importante: Todas las rutas llevan el prefijo /timbrado-api. No usar /api/v1/... en la raíz del dominio — esa ruta corresponde al portal web.

1. Descripción general

Equivalente HTTP/JSON del servicio WCF DetecnoPac.svc. Operaciones:

Timbrar CFDI 4.0 (síncrono)
Cancelar CFDI con XML de cancelación
Recuperar TFD por UUID
Recuperar acuse de envío
Consultar hora oficial del servidor PAC

Característica	Valor
Protocolo	HTTPS (TLS obligatorio)
Respuesta	JSON (camelCase)
Envío timbrado/cancelación	XML en el body
Autenticación	Headers `X-Usuario` / `X-Password`
Tamaño máximo CFDI	100 MB (104 857 600 bytes)
CFDI grandes	Preferir API Timbrado Async (`/timbrado-api-async`)

2. Autenticación

Header	Obligatorio	Descripción
`X-Usuario`	Sí	Usuario de timbrado asignado por Detecno
`X-Password`	Sí	Contraseña de timbrado
`X-Origen`	Solo POST /timbrado	Identificador del sistema origen (ej. ERP-MiEmpresa)
`X-Rfc-Emisor`	Solo cancelación	RFC del emisor (alternativa a query `rfcEmisor`)

No se utiliza JWT, OAuth ni API Key. En Swagger use el botón Authorize para pruebas manuales.

3. Endpoints

Operación	Método	Ruta (producción)	Body / params
Timbrar CFDI	POST	/timbrado-api/api/v1/timbrado	XML + `X-Origen`
Cancelar CFDI	POST	/timbrado-api/api/v1/cancelacion	XML + `rfcEmisor`
Recuperar TFD	GET	/timbrado-api/api/v1/timbrado/{uuid}/tfd	`?docId=`
Acuse de envío	POST	/timbrado-api/api/v1/acuse-envio	`?uuid=`
Hora servidor	GET	/timbrado-api/api/v1/hora-servidor	Sin credenciales

4. Formato de respuestas

Timbrado (HTTP 200, incluso si el PAC rechaza)

{
  "success": true,
  "docId": "string",
  "xmlTfd": "<?xml version=\"1.0\"...>",
  "strQr": "string",
  "errCode": "string",
  "errDesc": "string",
  "serverTime": "2026-06-16T15:00:00Z",
  "correlationId": "abc123..."
}

Campo	Descripción
`success`	true si el timbrado fue exitoso
`xmlTfd`	CFDI timbrado con Timbre Fiscal Digital
`correlationId`	ID de trazabilidad — incluir en soporte
`errCode` / `errDesc`	Error de negocio cuando success es false

Semántica HTTP

Situación	HTTP	Acción
Rechazo PAC / validación	200	Revisar success, errCode, errDesc
Headers o body inválidos	400	Revisar campo error
Error interno	500	Reintentar; reportar correlationId

5. Ejemplos

Timbrar CFDI (curl)

curl -s -X POST "https://mpn8.timbrame-factura-electronica.com/timbrado-api/api/v1/timbrado" \
  -H "Content-Type: application/xml; charset=utf-8" \
  -H "X-Usuario: SU_USUARIO" \
  -H "X-Password: SU_PASSWORD" \
  -H "X-Origen: mi-sistema-erp" \
  --data-binary "@cfdi.xml"

Cancelación

curl -s -X POST "https://mpn8.timbrame-factura-electronica.com/timbrado-api/api/v1/cancelacion?rfcEmisor=ABC010101ABC" \
  -H "Content-Type: application/xml" \
  -H "X-Usuario: SU_USUARIO" \
  -H "X-Password: SU_PASSWORD" \
  --data-binary "@cancelacion.xml"

C# (HttpClient)

using var client = new HttpClient {
    BaseAddress = new Uri("https://mpn8.timbrame-factura-electronica.com/timbrado-api")
};
var xml = await File.ReadAllTextAsync("cfdi.xml");
using var content = new StringContent(xml, Encoding.UTF8, "application/xml");
using var request = new HttpRequestMessage(HttpMethod.Post, "/api/v1/timbrado") { Content = content };
request.Headers.Add("X-Usuario", "SU_USUARIO");
request.Headers.Add("X-Password", "SU_PASSWORD");
request.Headers.Add("X-Origen", "mi-app");
var response = await client.SendAsync(request);

6. Migración desde WCF

WCF (DetecnoPac)	REST
TimbrarCfdi(...)	POST /timbrado-api/api/v1/timbrado
CancelacionCfdiConXML(...)	POST /timbrado-api/api/v1/cancelacion
RecuperarTfd(...)	GET /timbrado-api/api/v1/timbrado/{uuid}/tfd?docId=...
RecuperarAcuseEnvio(...)	POST /timbrado-api/api/v1/acuse-envio?uuid=...
ObtenerHoraServidor()	GET /timbrado-api/api/v1/hora-servidor

7. Buenas prácticas

Evaluar siempre success en el JSON, no solo el HTTP status.
Guardar correlationId para soporte y auditoría.
Enviar CFDI como XML con Content-Type: application/xml.
Timeout del cliente HTTP ≥ 120 segundos.
No reintentar timbrados exitosos — evita duplicados.
Usar X-Origen con valor estable por sistema.

8. Errores frecuentes

Síntoma	Causa	Acción
Swagger muestra Hash Validator	Spec cargado desde /swagger raíz	Usar /timbrado-api/swagger
400 headers requeridos	Falta X-Usuario o X-Password	Verificar headers
404 en /api/v1/timbrado	Falta prefijo /timbrado-api	Usar URL completa
success false, tamaño	XML > 100 MB	Reducir XML o usar API Timbrado Async

9. Timbrado async (CFDI grandes, hasta 100 MB)

Recurso	URL
Swagger	https://mpn8.timbrame-factura-electronica.com/timbrado-api-async/swagger
Enviar CFDI	POST /timbrado-api-async
Consultar estado	GET /timbrado-api-async/{transactionId}

10. Soporte

Al reportar incidencias incluir: correlationId, fecha/hora UTC, X-Usuario (sin password), X-Origen, endpoint, errCode/errDesc.

Detecno ClientGate — API REST Timbrado