Créditos y Facturación
La API de TPC soporta dos modelos de facturación:
Modelos de facturación
PREPAGO — créditos
Tu empresa compra un paquete de créditos (guías). Cada vez que creas una guía con POST /guias o POST /guias/batch, se descuenta 1 crédito por guía del saldo disponible, excepto cuando el destinatario paga el envío en la puerta (modalidadCobro COD_PRODUCTO_ENVIO o ENVIO_POR_COBRAR): ahí el envío ya se cobra al entregar y no se consume crédito. Tampoco se consume en COD_PRODUCTO con descontarEnvioDelCobro: true: el envío se descuenta del depósito del cobro.
- Si no tienes saldo suficiente, recibes
402 PAYMENT_REQUIRED - El saldo es la suma de todos tus paquetes activos: los créditos se toman del paquete más antiguo primero y, si no alcanza, del siguiente
- Para lotes (
/guias/batch), el débito y la creación de todas las guías ocurren en una sola operación — o se crean todas o ninguna; no existe escenario donde parte del lote se crea y parte no por falta de créditos - Adquiere más créditos desde el portal de clientes en la sección Facturación
¿De qué saldo descuenta cada token?
| Configuración de la empresa | Token de la empresa (o de la sucursal matriz) | Token de una sucursal |
|---|---|---|
| Créditos compartidos activado | Saldo de toda la empresa | Saldo de toda la empresa |
| Créditos compartidos desactivado | Créditos comprados por la matriz | Solo los créditos comprados por esa sucursal |
Con los créditos sin compartir, el token de una sucursal nunca gasta créditos de otra. El ajuste se cambia desde el portal (Sucursales) y la API lo aplica de inmediato.
POSTPAGO — empresas aprobadas
El acceso a la API requiere dos condiciones independientes:
| Condición | Descripción |
|---|---|
estadoVerificacion = APROBADA | TPC habilitó el acceso a la API para tu empresa |
modalidadFacturacion = POSTPAGO | Tienes un plan corporativo activo — no se requieren créditos previos |
Solo cuando ambas condiciones se cumplen se omite el cobro por créditos. La facturación se realiza por periodo acordado con TPC.
Si tu empresa tiene APROBADA pero está en modalidad PREPAGO (por ejemplo, después de cancelar un plan corporativo), las guías siguen requiriendo créditos normalmente.
Si tu empresa es POSTPAGO y recibes 402, verifica que el plan corporativo sigue activo. Contacta a TPC si el problema persiste.
Error PAYMENT_REQUIRED (402)
{
"success": false,
"error": {
"message": "Sin créditos disponibles. Adquiere más créditos en el portal.",
"code": "PAYMENT_REQUIRED"
}
}Causas:
| Causa | Solución |
|---|---|
| Saldo en 0 (PREPAGO) | Compra créditos en el portal |
| Empresa sin acceso API | Solicita verificación desde Perfil → Mi empresa |
| Plan corporativo desactivado | La empresa volvió a PREPAGO — adquiere créditos o reactiva el plan |
| Plan vencido o suspendido | Contacta a soporte TPC |
Interacción con el sandbox
En modo sandbox (token tpc_test_…), no se debitan créditos bajo ninguna circunstancia. El saldo de tu cuenta nunca cambia al usar el token de pruebas.
El límite diario de guías sí se monitorea en sandbox, pero con un contador separado — las pruebas no consumen tu cuota de producción de 500 guías/día.
Ver Sandbox para más detalles.
Ver tu saldo
El saldo actual no está expuesto en la API pública — consúltalo en el portal de clientes bajo Facturación. Si necesitas acceso programático al saldo, contacta a TPC.