ES | EN

Ejemplos por país

✅ Buenas prácticas

1. Gestionar el access_token de forma eficiente

Es fundamental gestionar el access_token obtenido desde /auth de forma eficiente para evitar limitaciones de velocidad (rate limiting) y bloqueos de IP. Esto es especialmente importante cuando se procesan altos 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

// Solicitud al endpoint /auth
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 dentro de este período
  • Solo solicite un nuevo token cuando el actual expire o esté a punto de expirar
  • Esto evita solicitudes de autenticación excesivas que podrían activar límites 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 agregarlas a 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 al 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

Respete siempre 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 especificado en su contrato
  2. Implemente retroceso exponencial: Al recibir un error 429, espere al menos 30 segundos antes de reintentar
  3. Gestione los reintentos correctamente: Implemente un mecanismo de reintento con demoras adecuadas

Ejemplo: Gestión de errores 429

// Respuesta de error cuando se supera el límite de velocidad
HTTP/1.1 429 Too Many Requests
Content-Type: application/json

Recomendación de implementación:

# Ejemplo de pseudocódigo
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 usando 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 tributarios) que contenga su ID de transacción interno.

Envío de un documento con referencia

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

{
  "header": {
    "account_id": 14540,
    "document_type_id": "82",
    "received_issued_flag": 0,
    "issue_date": "2025-01-14",
    "issuer_tax_id_code": "860517022-2",
    "issuer_tax_id_type": "CO-NIT",
    "issuer_legal_name": "Your Company Name",
    "issuer_address": "Your Address",
    "issuer_district": "Your District",
    "issuer_city": "Your City",
    "issuer_country_id": "66",
    "issuer_phone": "Your Phone",
    "issuer_activity": "Your Activity",
    "receiver_tax_id_code": "860517022-2",
    "receiver_tax_id_type": "CO-NIT",
    "receiver_legal_name": "Receiver Name",
    "receiver_address": "Receiver Address",
    "receiver_county_id": "496",
    "receiver_country_id": "66",
    "receiver_phone": "Receiver Phone",
    "receiver_activity": "Receiver Activity",
    "payment_conditions": "0",
    "currency_id": 28
  },
  "details": [
    {
      "quantity": 1,
      "line_description": "Product Description",
      "unit_measure": "UN",
      "unit_price": 1500,
      "long_description": "Detailed description",
      "modifier_amount": -100,
      "total_taxes": 266,
      "modifier_percentage": 0,
      "total_amount_line": 1666,
      "taxes": [
        {
          "tax_type_id": "388",
          "tax_percentage": 19,
          "tax_amount": 266
        }
      ]
    }
  ],
  "references": [
    {
      "reference_number": "TXN-2025-001234",
      "reference_code": 5,
      "description": "Internal transaction ID"
    }
  ],
  "totals": {
    "net_amount": 1400,
    "taxes_amount": 266,
    "total_amount": 1666
  }
}

Puntos clave:

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

Búsqueda de documentos por referencia

Para verificar si ya existe un documento con una referencia específica, use 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": "FV-2025-001234",
        "issue_date": "2025-01-14",
        ...
      },
      "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 al 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 se encuentra, use el document_id existente en lugar de crear un duplicado
  3. Si no se encuentra, proceda con la creación del documento incluyendo el campo de referencia
  4. Esto garantiza la idempotencia y evita documentos duplicados

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