ES | EN

Ejemplos por país

✅ Buenas prácticas

Buenas prácticas

1. Gestionar el access_token de manera eficiente

Es fundamental gestionar el access_token obtenido de /auth de manera eficiente para evitar limitaciones de velocidad y bloqueos de IP. Esto es especialmente importante cuando se procesan grandes volúmenes de documentos.

Buena práctica: Almacene el access_token durante 60 minutos y reutilícelo para todas las emisiones de documentos posteriores. No solicite un nuevo token por cada creación de documento.

Ejemplo: Gestión del token

// Request to /auth endpoint
POST https://api-billing.koywe.com/V1/auth
Content-Type: application/json

{
    "grant_type": "password",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "username": "your_username",
    "password": "your_password"
}

Respuesta:

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

Recomendación de implementación:

  • Almacene en caché el access_token con un TTL de 60 minutos (3600 segundos)
  • Reutilice el mismo token para todas las llamadas a la API durante este período
  • Solo solicite un nuevo token cuando el actual expire o esté próximo a expirar
  • Esto evita solicitudes de autenticación excesivas que podrían activar limitaciones de velocidad en su IP

2. Lista blanca de IPs (para altos volúmenes)

Si su sistema procesa más de 5 documentos por segundo, debe proporcionarnos sus direcciones IP para incluirlas en la lista blanca y evitar posibles bloqueos.

Por qué es importante:

  • El tráfico de alto volumen puede activar medidas de seguridad
  • La lista blanca garantiza que sus IPs no sean bloqueadas
  • Contacte a soporte para agregar sus IPs a la lista blanca

Acción requerida: Contacte a su representante de ventas con:

  • Sus direcciones IP de producción
  • Volumen esperado (documentos por segundo)
  • Información de la cuenta

3. Respetar los límites de velocidad y gestionar errores 429

Siempre respete los límites de velocidad definidos en su contrato. Si supera el límite, recibirá un error 429 Too Many Requests.

Buenas prácticas:

  1. Monitoree su tasa de solicitudes: No supere el límite de velocidad especificado en su contrato
  2. Implemente retroceso exponencial: Al recibir un error 429, espere al menos 30 segundos antes de volver a intentarlo
  3. Gestione los reintentos adecuadamente: Implemente un mecanismo de reintento con los retardos apropiados

Ejemplo: Manejo de errores 429

// Error response when rate limit is exceeded
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

Recomendación de implementación:

# Pseudo-code example
def create_document_with_retry(document_data, access_token):
    max_retries = 3
    backoff_seconds = 30

    for attempt in range(max_retries):
        try:
            response = post_document(document_data, access_token)
            return response
        except HTTPError as e:
            if e.status_code == 429:
                if attempt < max_retries - 1:
                    time.sleep(backoff_seconds)
                    continue
                else:
                    raise Exception("Rate limit exceeded after retries")
            else:
                raise

4. Prevenir duplicados utilizando el campo de referencia

Para evitar la creación de documentos duplicados al reintentar solicitudes, utilice el campo reference con reference_code 5 (referencia a otros documentos no fiscales) que contenga su ID de transacción interno.

Enviar un documento con referencia

Al crear un documento, incluya el array references con su ID de transacción interno:

{
  "header": {
    "account_id": 11857,
    "document_type_id": "76",
    "issue_date": "2025-01-07",
    "issuer_tax_id_code": "EKU9003173C9",
    "issuer_tax_id_type": "MX-RFC",
    "issuer_legal_name": "ESCUELA KEMPER URGATE",
    "issuer_address": "Calle roja 234",
    "issuer_city": "Ciudad de méxico",
    "issuer_country_id": "80",
    "issuer_phone": "2223334444",
    "issuer_activity": "601",
    "issuer_postalcode": "42501",
    "receiver_tax_id_code": "EKU9003173C9",
    "receiver_tax_id_type": "MX-RFC",
    "receiver_legal_name": "ESCUELA KEMPER URGATE",
    "receiver_address": "Calle naranja 123",
    "receiver_city": "Cancún",
    "receiver_country_id": "80",
    "receiver_phone": "2223334444",
    "receiver_activity": "601",
    "receiver_postalcode": "42501",
    "payment_conditions": "0",
    "currency_id": 31,
    "additional": {
      "mx_header": {
        "receiver_cfdi_usage": "G03",
        "reported_payment_code": "01"
      }
    }
  },
  "details": [
    {
      "quantity": 1,
      "sku": "SKU001",
      "line_description": "Product Description",
      "unit_measure": "UN",
      "unit_price": 1500,
      "long_description": "Detailed description",
      "modifier_amount": -100,
      "total_taxes": 224,
      "modifier_percentage": 0,
      "total_amount_line": 1624,
      "taxes": [
        {
          "tax_type_id": "362",
          "tax_percentage": 16,
          "tax_amount": 224
        }
      ],
      "additional": {
        "mx_detail": {
          "product_service_identifier": "01010101",
          "measure_unit_code": "E48"
        }
      }
    }
  ],
  "references": [
    {
      "reference_number": "TXN-2025-001234",
      "reference_code": 5,
      "description": "Internal transaction ID"
    }
  ],
  "totals": {
    "net_amount": 1400,
    "taxes_amount": 224,
    "total_amount": 1624
  }
}

Puntos clave:

  • reference_number: Su ID de transacción interno (ej., "TXN-2025-001234")
  • reference_code: 5 (referencia a otros documentos no fiscales)

Buscar documentos por referencia

Para verificar si ya existe un documento con una referencia específica, utilice el endpoint GET /documents con parámetros de consulta:

Endpoint: GET https://api-billing.koywe.com/V1/documents

Parámetros de consulta:

  • reference_code: 5 (para filtrar por código de referencia)
  • reference_number: Su ID de transacción interno (ej., TXN-2025-001234)

Ejemplo de solicitud:

GET https://api-billing.koywe.com/V1/documents?reference_code=5&reference_number=TXN-2025-001234
Authorization: Bearer <your_access_token>
Accept: */*

Ejemplo de respuesta:

{
  "data": [
    {
      "document_id": 12345,
      "header": {
        "document_number": "ABC1234567890",
        "issue_date": "2025-01-07",
        ...
      },
      "references": [
        {
          "reference_number": "TXN-2025-001234",
          "reference_code": 5,
          "description": "Internal transaction ID"
        }
      ],
      ...
    }
  ],
  "pagination": {
    "total": 1,
    "per_page": 20,
    "current_page": 1
  }
}

Recomendación de implementación cuando vaya a reintentar la emisión:

  1. Antes de crear un documento, verifique si ya existe uno con su ID de transacción interno (NO incluya esta validación en cada emisión común o tendrá problemas de rendimiento)
  2. Si lo encuentra, utilice el document_id existente en lugar de crear un duplicado
  3. Si no lo encuentra, proceda con la creación del documento incluyendo el campo de referencia
  4. Esto garantiza la idempotencia y evita documentos duplicados

Note: Resumen: Siga estas buenas prácticas para una emisión de documentos confiable: almacene en caché su token de acceso, ponga sus IPs en lista blanca (si procesa altos volúmenes), respete los límites de velocidad con retroceso adecuado y utilice campos de referencia para evitar duplicados.