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 limitaciones de tasa 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 de tokens

// 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 ese 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 tasa 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 tasa y gestionar los errores 429

Respete siempre los límites de tasa definidos en su contrato. Si los supera, recibirá un error 429 Too Many Requests.

Buenas prácticas:

  1. Monitoree su tasa de solicitudes: No exceda el límite de tasa 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 apropiadas

Ejemplo: Gestión 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 reference

Para evitar la creación de documentos duplicados al reintentar solicitudes, use el campo reference con reference_code 5 (referencia a otros documentos no tributarios) 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": 16268,
    "document_type_id": "96",
    "received_issued_flag": 0,
    "issue_date": "2025-02-03",
    "issuer_tax_id_code": "20610383727",
    "issuer_tax_id_type": "PE-RUC",
    "issuer_legal_name": "Your Company Name",
    "issuer_address": "Your Address",
    "issuer_district": "Your District",
    "issuer_city": "Your City",
    "issuer_department": "Your Department",
    "issuer_country_id": "83",
    "issuer_phone": "Your Phone",
    "issuer_activity": "Your Activity",
    "issuer_postalcode": "12345456",
    "receiver_tax_id_code": "20473731828",
    "receiver_tax_id_type": "PE-RUC",
    "receiver_legal_name": "Receiver Name",
    "receiver_address": "Receiver Address",
    "receiver_district": "Receiver District",
    "receiver_city": "Receiver City",
    "receiver_department": "Receiver Department",
    "receiver_country_id": "83",
    "receiver_phone": "Receiver Phone",
    "receiver_activity": "Receiver Activity",
    "receiver_postalcode": "12343456",
    "payment_conditions": "0",
    "currency_id": 7,
    "additional": {
      "pe_header": {
        "signature_id": "ASDFG",
        "operation_type": "0101"
      }
    }
  },
  "details": [
    {
      "quantity": 1,
      "line_description": "Product Description",
      "unit_measure": "NIU",
      "unit_price": 1000,
      "long_description": "Detailed description",
      "modifier_amount": 0,
      "total_taxes": 180,
      "modifier_percentage": 0,
      "total_amount_line": 1180,
      "sku": "SKU001",
      "taxes": [
        {
          "tax_type_id": "413",
          "tax_percentage": 18,
          "tax_amount": 180
        }
      ]
    }
  ],
  "references": [
    {
      "reference_number": "TXN-2025-001234",
      "reference_code": 5,
      "description": "Internal transaction ID"
    }
  ],
  "totals": {
    "net_amount": 1000,
    "taxes_amount": 180,
    "total_amount": 1180
  }
}

Puntos clave:

  • reference_number: Su ID de transacción interno (ej., "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_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": "F001-000123",
        "issue_date": "2025-02-03",
        ...
      },
      "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 previene documentos duplicados

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