ES | EN

Ejemplos por país

✅ Buenas prácticas

1. Gestionar el access_token de manera eficiente

Es fundamental gestionar el access_token obtenido desde /auth de manera eficiente para evitar limitaciones de tasa e bloqueos de IP. Esto es especialmente importante al procesar grandes volúmenes de documentos.

Buena práctica: Almacena el access_token durante 60 minutos y reutilízalo para todas las emisiones de documentos posteriores. No solicites 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:

  • Cachea el access_token con un TTL de 60 minutos (3600 segundos)
  • Reutiliza el mismo token para todas las llamadas a la API dentro de este período
  • Solicita un nuevo token solo cuando el actual expire o esté a punto de hacerlo
  • Esto evita solicitudes de autenticación excesivas que podrían desencadenar limitaciones de tasa en tu IP

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

Si tu sistema procesa más de 5 documentos por segundo, debes proporcionarnos tus 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 tus IPs no sean bloqueadas
  • Contacta a soporte para agregar tus IPs a la lista blanca

Acción requerida: Contacta a tu representante de ventas con:

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

3. Respetar los límites de tasa y manejar errores 429

Respeta siempre los límites de tasa definidos en tu contrato. Si superas el límite, recibirás un error 429 Too Many Requests.

Buenas prácticas:

  1. Monitorea tu tasa de solicitudes: No superes el límite de tasa especificado en tu contrato
  2. Implementa retroceso exponencial: Al recibir un error 429, espera al menos 30 segundos antes de reintentar
  3. Maneja los reintentos con cuidado: Implementa un mecanismo de reintento con demoras adecuadas

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. Evitar duplicados usando el campo reference

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

Enviar un documento con referencia

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

{
  "header": {
    "account_id": 12345,
    "document_type_id": "111",
    "received_issued_flag": 1,
    "issue_date": "2025-01-07",
    "issuer_tax_id_code": "20-12345678-9",
    "issuer_tax_id_type": "AR-CUIT",
    "issuer_legal_name": "Your Company Name",
    "issuer_address": "Your Address",
    "issuer_district": "Your District",
    "issuer_city": "Your City",
    "issuer_country_id": "10",
    "issuer_phone": "Your Phone",
    "issuer_activity": "Your Activity",
    "receiver_tax_id_code": "20-12345678-9",
    "receiver_tax_id_type": "AR-CUIT",
    "receiver_legal_name": "Receiver Name",
    "receiver_address": "Receiver Address",
    "receiver_district": "Receiver District",
    "receiver_city": "Receiver City",
    "receiver_country_id": "10",
    "receiver_phone": "Receiver Phone",
    "receiver_activity": "Receiver Activity",
    "payment_conditions": "0",
    "currency_id": 1
  },
  "details": [
    {
      "quantity": 1,
      "sku": "SKU001",
      "line_description": "Product Description",
      "unit_measure": "UN",
      "unit_price": 1500,
      "long_description": "Detailed description",
      "modifier_amount": 0,
      "total_taxes": 315,
      "modifier_percentage": 0,
      "total_amount_line": 1815,
      "taxes": [
        {
          "tax_type_id": "1",
          "tax_percentage": 21,
          "tax_amount": 315
        }
      ]
    }
  ],
  "references": [
    {
      "reference_number": "TXN-2025-001234",
      "reference_code": 5,
      "description": "Internal transaction ID"
    }
  ],
  "totals": {
    "net_amount": 1500,
    "taxes_amount": 315,
    "total_amount": 1815
  }
}

Puntos clave:

  • reference_number: Tu 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, usa 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: Tu 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": "0001-00001234",
        "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 al reintentar la emisión:

  1. Antes de crear un documento, verifica si ya existe uno con tu ID de transacción interno (NO incluyas esta validación en cada emisión común, o tendrás problemas de rendimiento)
  2. Si lo encuentras, usa el document_id existente en lugar de crear un duplicado
  3. Si no lo encuentras, procede con la creación del documento incluyendo el campo reference
  4. Esto garantiza la idempotencia y evita documentos duplicados

Nota: Resumen: Sigue estas buenas prácticas para una emisión de documentos confiable: cachea tu token de acceso, incluye tus IPs en la lista blanca (si procesas altos volúmenes), respeta los límites de tasa con retroceso adecuado y usa campos de referencia para evitar duplicados.