ES | EN

Ejemplos por país

✅ Buenas prácticas

1. Gestionar el access_token de forma eficiente

Es fundamental gestionar el access_token obtenido de /auth de manera eficiente para evitar límites 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 para 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 dentro de este período
  • Solo solicite un nuevo token cuando el actual expire o esté a punto de hacerlo
  • Esto previene 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 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 manejar errores 429

Respete siempre los límites de velocidad definidos en su contrato. Si supera el límite de velocidad, 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: Cuando reciba un error 429, espere al menos 30 segundos antes de reintentar
  3. Maneje los reintentos con gracia: Implemente un mecanismo de reintento con los retrasos adecuados

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 usando el campo de referencia

Para evitar la creación de documentos duplicados al reintentar solicitudes, use el campo reference con reference_type 802 (Nota de pedido) 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": 423,
    "document_type_id": "2",
    "received_issued_flag": 1,
    "issue_date": "2025-01-07",
    "issuer_tax_id_code": "76399932-7",
    "issuer_tax_id_type": "CL-RUT",
    "issuer_legal_name": "Your Company Name",
    "issuer_address": "Your Address",
    "issuer_district": "Your District",
    "issuer_city": "Your City",
    "issuer_country_id": "253",
    "issuer_phone": "Your Phone",
    "issuer_activity": "Your Activity",
    "receiver_tax_id_code": "76399932-7",
    "receiver_tax_id_type": "CL-RUT",
    "receiver_legal_name": "Receiver Name",
    "receiver_address": "Receiver Address",
    "receiver_district": "Receiver District",
    "receiver_city": "Receiver City",
    "receiver_country_id": "253",
    "receiver_phone": "Receiver Phone",
    "receiver_activity": "Receiver Activity",
    "payment_conditions": "0",
    "currency_id": 39
  },
  "details": [
    {
      "quantity": 1,
      "sku": "SKU001",
      "line_description": "Product Description",
      "unit_measure": "UN",
      "unit_price": 1500,
      "long_description": "Detailed description",
      "modifier_amount": 0,
      "total_taxes": 285,
      "modifier_percentage": 0,
      "total_amount_line": 1785,
      "taxes": [
        {
          "tax_type_id": "387",
          "tax_percentage": 19,
          "tax_amount": 285
        }
      ]
    }
  ],
  "references": [
    {
      "reference_type": 802,
      "reference_number": "TXN-2025-001234",
      "reference_code": 5,
      "description": "Internal transaction ID"
    }
  ],
  "totals": {
    "net_amount": 1500,
    "taxes_amount": 285,
    "total_amount": 1785
  }
}

Puntos clave:

  • reference_type: 802 (Nota de pedido) - utilizado para referencias de documentos no tributarios
  • reference_number: Su ID de transacción interno (por ejemplo, "TXN-2025-001234")
  • reference_code: 5 (referencia a otros documentos no tributarios)

Buscar 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_type: 802 (para filtrar por tipo de referencia)
  • reference_number: Su ID de transacción interno (por ejemplo, TXN-2025-001234)

Ejemplo de solicitud:

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

Ejemplo de respuesta:

{
  "data": [
    {
      "document_id": 12345,
      "header": {
        "document_number": "F001-000123",
        "issue_date": "2025-01-07",
        ...
      },
      "references": [
        {
          "reference_type": 802,
          "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 previene documentos duplicados

Nota: Resumen: Siga estas buenas prácticas para una emisión confiable de documentos: 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 prevenir duplicados.